Events

Webhooks

Register one HTTPS endpoint. Tunnel forwards normalized events as payments move through pending → successful / failed — regardless of which provider handled the charge.

Register an endpoint

In the dashboard go to Webhooks, or call the API:

POST/v1/webhooks

Create a webhook subscription

Request
{
  "url": "https://api.yourapp.com/webhooks/tunnel",
  "events": [
    "transaction.pending",
    "transaction.successful",
    "transaction.failed"
  ]
}
cURL
curl -X POST "https://xv9ni4gwk9.execute-api.us-east-1.amazonaws.com/dev/v1/webhooks" \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -H "X-Tunnel-Origin: https://api.yourapp.com" \
  -d '{
    "url": "https://api.yourapp.com/webhooks/tunnel",
    "events": ["transaction.pending", "transaction.successful", "transaction.failed"]
  }'

Event types

EventWhen
transaction.pendingCheckout initialized with the provider
transaction.processingVerification started
transaction.successfulPayment confirmed
transaction.failedPayment failed

Example payload

transaction.successful
{
  "event": "transaction.successful",
  "data": {
    "transactionId": "txn_8f2a1c0b4e9d7a6c",
    "amount": 500000,
    "currency": "NGN",
    "status": "successful",
    "provider": "paystack"
  }
}

A transaction.failed payload also carries failureCode and failureReason when the provider says why, for example amount_mismatch for a bank transfer that was underpaid.

Retries

Answer with any 2xx status to confirm a delivery. If your endpoint answers anything else, or does not answer within 10 seconds, Tunnel tries again up to six times in all: about 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours after the previous attempt. After that the event is marked failed.

A retry can arrive even when your first answer was lost, so make your handler safe to run twice. Every delivery carries X-Tunnel-Event-Id, the same on each retry, and X-Tunnel-Delivery-Attempt. The body also has the event id.

Verify signatures

Use the webhook secret from your dashboard to validate deliveries before updating orders. Reject unsigned or mismatched requests. Prefer webhooks for fulfilment; use verify as a fallback or reconciliation check.

Also see error codes →