​

Webhooks

• a receiver webhook to the receiving application’s transactionWebhookUrl
• a sender callback to the sender’s callbackUrl (or sender app transactionWebhookUrl fallback)

​

1) Receiver webhook

• Target: transactionWebhookUrl on the receiving app
• Event name: TRANSACTION_INITIATED
• Purpose: notify the receiver that a payment request needs acceptance or rejection

{
  "event": "TRANSACTION_INITIATED",
  "transaction": {
    "reference": "TXN-9812345678-A1B2C3D4",
    "senderTag": "alice@walletapp",
    "senderAppName": "WalletApp",
    "receiverTag": "bob@shopapp",
    "receiverAppName": "ShopApp",
    "amount": 500.0000,
    "currency": "NGN",
    "narration": "Payment for order #99",
    "expiresAt": "2024-03-16T12:00:00Z",
    "createdAt": "2024-03-16T11:55:00Z"
  }
}

​

2) Sender callback

• Target: sender’s callbackUrl, or if not supplied, the sender app’s transactionWebhookUrl
• Event names:
  • TRANSACTION_COMPLETED
  • TRANSACTION_REJECTED
  • TRANSACTION_EXPIRED
• Purpose: inform the sender of the final result

{
  "event": "TRANSACTION_COMPLETED",
  "transaction": {
    "reference": "TXN-9812345678-A1B2C3D4",
    "senderTag": "alice@walletapp",
    "senderAppName": "WalletApp",
    "receiverTag": "bob@shopapp",
    "receiverAppName": "ShopApp",
    "amount": 500.0000,
    "currency": "NGN",
    "narration": "Payment for order #99",
    "expiresAt": "2024-03-16T12:00:00Z",
    "createdAt": "2024-03-16T11:55:00Z"
  }
}

​

Payload rules

• event: one of TRANSACTION_INITIATED, TRANSACTION_COMPLETED, TRANSACTION_REJECTED, TRANSACTION_EXPIRED
• transaction: the transaction snapshot with:
  • reference
  • sender and receiver tag names
  • sender and receiver app IDs/names
  • amount, currency, narration
  • createdAt and expiresAt

​

Encryption

• Header: Content-Encryption: JWE
• Decrypt using the application’s own private key after validating the webhook signature
• The signature is still computed over the raw HTTP body that was delivered

​

Signature verification

• X-Switch-Timestamp
• X-Switch-Signature

v0=<hex(HMAC-SHA256(webhookSecret, "v0:" + timestamp + ":" + body))>

​

Verification flow

1. Read the raw request body exactly as received.
2. Reject stale timestamps.
3. Recompute the HMAC with your webhookSecret.
4. Compare signatures in constant time.
5. If encryption is enabled, decrypt the payload next.
6. Return a 2xx response promptly.

​

Delivery expectations

• Switch retries failed webhook deliveries up to 3 times.
• Retry backoff is exponential.
• Failed deliveries can be inspected later through webhook-related endpoints.

​

Operational recommendations

• Treat webhook handling as idempotent.
• Persist delivery attempts by transaction/reference.
• Verify the signature before parsing business data.
• Decrypt only after signature validation when encryption is enabled.

​

Typical flow

Receive webhook
  -> verify X-Switch-Signature
  -> decrypt if Content-Encryption: JWE
  -> validate business rules
  -> for TRANSACTION_INITIATED: accept or reject
  -> return 2xx promptly

​

Related topics

• Quickstart
• Payments
• Integration guide