Webhooks

Receive real-time events for API-created banking transfers.

Banking webhooks notify your server when an API-created transfer changes state. Register endpoints from your dashboard under Developers → Banking.

Endpoint scope

Each webhook endpoint is product-scoped. An endpoint registered under Developers → Banking receives only banking events — it never receives card or checkout events. Each endpoint has its own verification token, and you can register more than one.

Event types

Event	When
`banking.transfer.pending`	An API-created transfer is created or updated and still processing.
`banking.transfer.completed`	A transfer reaches a completed status.
`banking.transfer.failed`	A transfer fails.
`banking.transfer.cancelled`	A transfer is cancelled.

Payload

Every delivery wraps the transfer in a common envelope. data is the same object the transfer endpoints return under transfer, so you can share status-handling code between the two.

{
  "id": "evt_01HXR9...",
  "type": "banking.transfer.completed",
  "createdAt": "2026-06-25T12:01:20.000Z",
  "livemode": true,
  "data": {
    "id": "7b4f1f9c-7d92-4d12-a4aa-9c5b2f4f9b25",
    "object": "banking.transfer",
    "status": "completed",
    "direction": "debit",
    "rail": "pix",
    "description": "Acme Ltda supplier payout",
    "memo": "Invoice 1048",
    "sourceCurrency": "USDC",
    "sourceAmount": "18.82",
    "destinationCurrency": "BRL",
    "destinationAmount": "100.00",
    "fxRate": "5.31349628",
    "recipientId": "9a5b47c1-234d-4841-a5b8-d1b790f774be",
    "idempotencyKey": "pix-acme-1048",
    "createdAt": "2026-06-25T12:00:00.000Z",
    "updatedAt": "2026-06-25T12:01:20.000Z",
    "completedAt": "2026-06-25T12:01:20.000Z"
  }
}

Verifying deliveries

Every request includes these headers:

X-Dolafy-Token — your per-endpoint verification token, shown once when the endpoint is created.
Dolafy-Event-Id — unique event id (also the body id).
Dolafy-Event-Type — the event type.
Dolafy-Delivery-Id — unique delivery id; retries of the same delivery reuse it.

Compare X-Dolafy-Token to the token you stored at creation and reject the request if it does not match. There is no HMAC signature — because the token is sent on every request, your endpoint must use HTTPS, keep the token secret, and avoid logging request headers. Rotate the token by recreating the endpoint.

Delivery semantics

Respond with a 2xx quickly, then process the event asynchronously.
Delivery is best-effort and single-attempt for banking events. There is no durable retry queue or replay endpoint.
Make your handlers idempotent by Dolafy-Event-Id (or Dolafy-Delivery-Id), and reconcile anything you may have missed with GET /v1/banking/transfers/:id.
Manual test deliveries sent from the dashboard include top-level "test": true. Never fulfil or move money from a test event.