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

Creates new webhook subscription or updates an existing one

Authorizations

Header parameters

Signaturestringrequired

HTTP message signature

Signature-Inputstringrequired

HTTP message signature input

Idempotency-Keystring · uuidrequired

Idempotency key (UUID)

Content-Digeststringrequired

Content digest

Body

idstring · uuidoptional

Unique ID of the webhook to be updated

callbackUrlstring · urirequired

URL to be subscribed for receiving events

Example: https://example.com/callback

typesstring · enum[]required

Types of events to be received by the callback

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url 'https://api.offblocks.xyz/v1/webhooks' \
  --header 'Authorization: Bearer JWT' \
  --header 'Signature: text' \
  --header 'Signature-Input: text' \
  --header 'Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000' \
  --header 'Content-Digest: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "callbackUrl": "https://example.com/callback",
    "types": [
      "customer.updated"
    ]
  }'

200

400

401

500

200

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "callbackUrl": "https://example.com/callback",
  "types": [
    "customer.updated"
  ],
  "createdAt": "2025-04-03T07:41:59.068Z",
  "updatedAt": "2025-04-03T07:41:59.068Z"
}

Successful operation

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"
}