OffBlocks
  • πŸ‘‹Welcome to OffBlocks
  • Overview
    • πŸ’‘What we do
    • ✨Core Concepts
    • πŸ“œWhitepaper
    • ⛓️Supported Blockchains and Assets
    • ❔FAQ
  • Developer Guides
    • πŸ—οΈSystem Architecture
    • βš™οΈAPI Integration
      • πŸš€Getting Started
      • πŸ“―Postman
      • πŸ”‘Authentication
      • πŸ”Request Signatures
      • πŸ†”Idempotency
      • ⛓️Blockchain Identifiers
      • πŸ“’Blockchain Updates
      • πŸ“²Sign in With X
      • πŸ’°Fees
      • πŸ•ΉοΈSimulator
      • πŸ”’API Reference
        • πŸ¦Έβ€β™‚οΈCustomers
        • 🏦Accounts
        • πŸ’³Cards
        • πŸ”ƒTransactions
        • πŸͺWebhooks
        • πŸ•ΉοΈSimulator
        • πŸš‚Engine
      • ⏭️States and Transitions
        • πŸ¦Έβ€β™‚οΈCustomer States
        • 🏦Account States
        • πŸ’³Card States
        • πŸ”‘Authorisation States
        • πŸ”ƒTransaction States
    • 🧬Smart Contracts
      • OffBlocksEscrow.sol
      • OffBlocksSmartWalletFactory.sol
      • OffBlocksSmartWallet.sol
      • PendingWithdrawal.sol
      • Interfaces
    • πŸ”’Step-by-step Guide
      • 1️⃣API Credentials
      • 2️⃣Authentication
      • 3️⃣Request Preparation
      • 4️⃣Customer Creation
      • 5️⃣Customer Verification
      • 6️⃣Account Creation
      • 7️⃣Card Issuance
      • 8️⃣Card Authorisations
      • 9️⃣Webhooks
  • Use Cases
    • πŸ’°Wallet Providers
    • πŸ§‘β€πŸŒΎDeFi Apps
    • 🏦Neo-banks and FinTechs
Powered by GitBook
On this page
  1. Developer Guides
  2. Step-by-step Guide

Webhooks

PreviousCard AuthorisationsNextWallet Providers

Last updated 1 year ago

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 . 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 , 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"
    ]
}

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

πŸ”’
9️⃣
https://webhook.site/
https://webhook.site/81f3f721-303e-4b3c-899f-57db55aa5262

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
Responses
200
Successful operation
application/json
400
Invalid request
401
Not authorised
500
Internal error
put
PUT /v1/webhooks HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer JWT
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-05-09T05:27:58.410Z",
  "updatedAt": "2025-05-09T05:27:58.410Z"
}