9️⃣Webhooks

This step is optional and can be done at any point. Active webhook subscription is not a pre-requisite for using OffBlocks API and is engineered for convenient asynchronous processing of events

If you want a simple test for webhook notifications, you can set up a catch-all webhook endpoint via https://webhook.site/. You will have a unique generated URL you can use to receive notifications from OffBlocks API.

Please, follow the steps from Webhooks to set up and manage webhook notifications. For example, to set up a webhook notification for all entities' updates as a POST request to https://webhook.site/81f3f721-303e-4b3c-899f-57db55aa5262, make a PUT request to /webhooks with the following payload:

{
    "callbackUrl": "https://webhook.site/81f3f721-303e-4b3c-899f-57db55aa5262",
    "types": [
        "customer.updated",
        "account.updated",
        "card.updated",
        "authorisation.updated",
        "transaction.updated"
    ]
}

Create new or update an existing webhook

put

https://api.offblocks.xyz/v1https://api.sandbox.offblocks.xyz/v1

/webhooks

Creates new webhook subscription or updates an existing one

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

SignaturestringRequired

HTTP message signature

Signature-InputstringRequired

HTTP message signature input

Idempotency-Keystring · uuidRequired

Idempotency key (UUID)

Content-DigeststringRequired

Content digest

Body

application/json

idstring · uuidOptional

Unique ID of the webhook to be updated

callbackUrlstring · uriRequired

URL to be subscribed for receiving events

Example: https://example.com/callback

Responses

200

Successful operation

application/json

400

Invalid request

401

Not authorised

500

Internal error

put

/webhooks

HTTPcURLJavaScriptPython

PUT /v1/webhooks HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer YOUR_SECRET_TOKEN
Signature: text
Signature-Input: text
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000
Content-Digest: text
Content-Type: application/json
Accept: */*
Content-Length: 119

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "callbackUrl": "https://example.com/callback",
  "types": [
    "customer.updated"
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "callbackUrl": "https://example.com/callback",
  "types": [
    "customer.updated"
  ],
  "createdAt": "2025-12-13T16:55:19.540Z",
  "updatedAt": "2025-12-13T16:55:19.540Z"
}

Once you create a new customer entity in step Customer Creation, you will receive a notification similar to the following:

{
  "chainId": "eip155:300:0x43158f45b5EbD7b1179130130DF00393928C2691",
  "createdAt": "2024-01-24T14:18:37.749861007Z",
  "eventId": "fb2ed25e-11b1-49ce-a703-75f0c2d58c09",
  "externalId": "5fb1479a-0ef4-418e-82b5-0eb76f8a3df9",
  "id": "29ca152b-a06a-5f6d-8f34-06a8f1250141",
  "status": "initiating",
  "updatedAt": "2024-01-24T14:18:37.749861007Z",
  "webhookType": "customer.updated"
}