Webhooks

StarData sends real-time transaction status updates to your registered webhook_url for asynchronous flows (pending transactions, delayed provider confirmations).

Payload Structure

When a transaction state changes, we will POST a payload to your endpoint.

JSON

{
  "event": "transaction.update",
  "reference": "DEV-A1B2C3D4E5",
  "status": "success",
  "amount": 320.00,
  "beneficiary": "08012345678",
  "service_type": "data",
  "timestamp": "2024-02-01T10:50:00Z",
  "meta": {
    "token": "5283-1234-5678-9012"
  }
}

Signature Verification

Every webhook request includes an X-Starboy-Signature header. Always verify this signature to ensure the payload is from StarData and hasn't been tampered with.

Algorithm: HMAC-SHA256
Secret: Your webhook_secret from GET /profile/

Python Example

Python

import hmac
import hashlib
import json
 
def verify_webhook(request_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        request_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)
 
# In your Django/Flask view:
signature = request.headers.get("X-Starboy-Signature")
is_valid = verify_webhook(request.body, signature, YOUR_WEBHOOK_SECRET)
 
if not is_valid:
    return HttpResponse(status=401)  # Reject invalid payloads

Node.js Example

JavaScript

const crypto = require('crypto');
 
function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
    
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Webhook Best Practices

Respond quickly: Respond with HTTP 200 OK within 5 seconds to prevent retries.
Idempotency: You may receive duplicate deliveries for the same event. Always check if you've already processed a webhook using its reference.
Security: Always verify the signature using HMAC-SHA256 before acting on the payload.
Logging: Log all incoming webhook events for auditing.