Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cadanapay.com/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks are automated HTTP POST requests sent by Cadana when events occur on the platform. Use them to get real-time updates for transactions, payroll, KYC, and more.

​
Webhook Structure

Every webhook follows this envelope structure:
JSON
{
  "eventType": "transaction.succeeded",
  "id": "e13b9e14-c062-42ea-8563-8fc9223b29b5",
  "version": "1.0",
  "timestamp": 1681006175,
  "data": {
    ...
  }
}
FieldDescription
idUnique webhook ID. Use this to deduplicate — retried webhooks are sent with the same id.
eventTypeThe event type (e.g., transaction.succeeded). See Events for the full list.
versionWebhook version
timestampUnix timestamp when the webhook was sent
dataEvent-specific payload. See Events for payload structures.

​
Getting Started

​
Configure Your Endpoint

  1. Navigate to Settings → Developers → Webhooks in the Dashboard
  2. Click Add Webhook
  3. Enter the URL where you want to receive events

​
Handle Events

After registering an endpoint, Cadana sends an HTTP POST request to your URL every time a subscribed event occurs. Parse the eventType field to determine how to handle each event.

​
Respond Promptly

Your endpoint must return a 2xx status code to acknowledge receipt. Any response outside the 2xx range — including 3xx redirects — is treated as a failure and will trigger retries.
Respond with 200 OK immediately, then process the payload asynchronously via a message queue. This prevents timeouts.

​
Verifying Webhooks

Every webhook includes signature headers you should verify to confirm it was sent by Cadana.

​
Signature Headers

HeaderDescription
svix-idUnique message ID from the delivery provider
svix-timestampUnix timestamp of the webhook
svix-signatureHMAC-SHA256 signature of the payload

​
Verification

Use the Svix libraries to verify signatures automatically:
JavaScript
import { Webhook } from "svix";

const wh = new Webhook("your-signing-secret");
const payload = wh.verify(body, headers);
Your signing secret is available in Settings → Developers → Webhooks in the Dashboard. For manual verification, see the Svix manual verification docs.

​
Retry Policy

If your endpoint fails to respond with a 2xx status code, Cadana retries delivery with exponential backoff:
AttemptDelay
1st retry5 seconds
2nd retry5 minutes
3rd retry30 minutes
4th retry2 hours
5th retry5 hours
6th retry10 hours
7th retry24 hours
After all retries are exhausted (~3 days), the webhook is marked as failed.

​
Best Practices

  1. Respond immediately — Return 200 OK first, process asynchronously. Don’t do heavy work before responding.
  2. Deduplicate — Use the id field to detect and skip duplicate deliveries. Retried webhooks keep the same id.
  3. Fetch the latest state — Webhooks can arrive out of order. After receiving an event, fetch the resource via API (e.g., GET /v1/payouts/{id}) to get the latest state.
  4. Implement reconciliation — Webhook delivery is not guaranteed. Periodically poll the API to catch any missed events.
  5. Verify signatures — Always verify the svix-signature header before processing a webhook to prevent spoofing.