Webhooks

Global webhooks

Configure one URL that receives every ledger event.

Global webhooks send ledger-wide events to a single URL you configure in Blnk. Use them for notifications, reconciliation outcomes, and system errors across your instance.

Payload contract

Each delivery is an HTTP POST with a JSON body in this shape:

{
  "event": "transaction.applied",
  "data": {
    "precise_amount": 20000,
    "amount": 200,
    "precision": 100,
    "transaction_id": "txn_9c2f1a8e-4b3d-4c91-9f2a-1a7b6c5d4e3f",
    "parent_transaction": "",
    "source": "bln_7f91a1ae-6073-4b7a-952c-23abf94a6634",
    "destination": "bln_59b83b9c-842c-427f-91eb-43cdeaf5c01a",
    "reference": "INV-2025-0008912",
    "currency": "GBP",
    "description": "Wallet top-up",
    "status": "APPLIED",
    "hash": "623e05ceb7ca7b02a9318092de7b75d8c668628e2db76c42b621b61055b10b3e",
    "allow_overdraft": true,
    "inflight": false,
    "skip_queue": false,
    "created_at": "2025-02-23T09:43:49.623494+01:00",
    "scheduled_for": "0001-01-01T00:00:00Z",
    "inflight_expiry_date": "0001-01-01T00:00:00Z"
  }
}

Delivery semantics

Blnk delivers webhooks at least once. Your endpoint may receive the same event more than once, often with an identical payload and X-Blnk-Signature.

Make handlers idempotent so a duplicate delivery does not trigger the same side effect twice, for example, sending two emails or crediting a balance twice. Dedupe on a stable key such as the event name plus the resource identifier in data, e.g. transaction_id.

Configuration

BLNK_WEBHOOK_URL=https://api.example.com/blnk/webhooks
BLNK_WEBHOOK_HEADERS={"Content-Type":"application/json","Authorization":"Bearer <your_auth_token>"}

{
  "notification": {
    "webhook": {
      "url": "https://api.example.com/blnk/webhooks",
      "headers": {
        "Content-Type": "application/json",
        "Authorization": "Bearer <your_auth_token>"
      }
    }
  }
}