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:
Create a webhook subscription
{
"url": "https://api.yourapp.com/webhooks/tunnel",
"events": [
"transaction.pending",
"transaction.successful",
"transaction.failed"
]
}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
| Event | When |
|---|---|
| transaction.pending | Checkout initialized with the provider |
| transaction.processing | Verification started |
| transaction.successful | Payment confirmed |
| transaction.failed | Payment failed |
Example payload
{
"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
Also see error codes →