API reference/Webhooks

Webhooks

Register an endpoint and receive signed events for every payout, disbursement, deposit and payment-request state change. Deliveries retry with backoff for 24 hours. Verify Decaf-Signature as HMAC-SHA256 over the timestamp, a dot, and the raw body; reject timestamps older than five minutes.

Events

Event	When
payout.submitted	Funds committed and handed to the rail
payout.awaiting_claim	Claim link sent
payout.claimed	Recipient claimed and chose a method
payout.succeeded	Delivered
payout.failed	Final failure after retries
payout.refunded	Funds returned after a failed delivery
disbursement.awaiting_approval	Submitted for approval
disbursement.launched	Execution started
disbursement.completed	Every item final and succeeded
disbursement.completed_with_failures	Every item final, at least one failed
deposit.received	A bank or on-chain deposit credited your balance
payment_request.paid	A fixed-amount request was matched

Register a webhook endpoint

POST/webhooks

Deliveries retry with backoff for 24 hours. The secret is shown once. Verify Decaf-Signature as HMAC-SHA256 over t + . + raw_body; reject timestamps older than five minutes.

Field	Type	required	Notes
url	string	required
events	array	required

Request

{
  "url": "https://example.com/decaf",
  "events": [
    "payout.*",
    "disbursement.*",
    "deposit.*"
  ]
}

Response 201

{
  "id": "wh_2c1d",
  "url": "https://example.com/decaf",
  "events": [
    "payout.*",
    "disbursement.*",
    "deposit.*"
  ],
  "secret": "whsec_9f3e..."
}

Examples: Register a webhook endpoint

curl -X POST https://sandbox.api.decaf.so/v1/webhooks \
  -H "Authorization: Bearer $DECAF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/decaf","events":["payout.*","disbursement.*","deposit.*"]}'

List webhooks

GET/webhooks

Delete a webhook

DELETE/webhooks/{id}

Parameters

idpathstringrequired

Get access

Build against the sandbox this week.

Tell us the corridors you need and the recipients you pay. Sandbox keys are issued by a person.