Receiving Webhooks

All webhooks are sent as HTTP POST requests to the URL configured in your Board settings.

Request format

HTTP Method: POST

Headers:

Content-Type: application/json
X-Hook-Checksum: <checksum_value>

Timeout: 10 seconds

Success response: Your endpoint must return HTTP 200 to acknowledge receipt. Any other status code will trigger a retry.

Payload structure

All webhook payloads follow this structure:

{
  "event_id": "EVENT#123e4567-e89b-12d3-a456-426614174000",
  "hook_id": "HOOK#2f6d8c1b-5f8f-4b3a-9d52-87a6f3bcd8c2",
  "event_type": "order.updated",
  "data": {
    // Entity-specific data (see below)
  },
  "signature": {
    "properties": ["order.id", "order.status", "order.amount"],
    "checksum": "124F3E92EA81EAC6DAB684035557433BA1922A7A47FED49F2001E831B5185C7E"
  },
  "timestamp": 1530291411,
  "sent_at": "2018-07-18T08:35:20.000Z"
}

Field descriptions

Name	Type	Description
event_id	string	Unique identifier for the event (prefixed with EVENT#). Use this for deduplication.
hook_id	string	Unique identifier for this delivery attempt (prefixed with HOOK#). Changes with each retry.
event_type	string	Type of event. See Webhook Events for available types.
data	object	Event-specific data containing the complete entity object (see below).
signature.properties	array	Properties used to generate the checksum. These may vary by event type.
signature.checksum	string	SHA256 hash for payload verification. See Verifying Signatures.
timestamp	integer	Unix timestamp (seconds) when this hook was sent.
sent_at	string	ISO 8601 timestamp when this hook was sent. Same time as timestamp, different format.

info

The X-Hook-Checksum header contains the same value as signature.checksum. Use whichever is more convenient for your implementation.

Data field structure

The data field contains the complete entity object as returned by the corresponding GET endpoint:

Event Type	Data Field	Equivalent API Response
order.updated	data.order	Same as GET /orders/{id}
payout.updated	data.payout	Same as GET /payouts/{id}
payout.item.updated	data.payout_item	Same as GET /payouts/{payout_id}/items/{item_id}
payin.updated	data.payin	Same as GET /payins/{id}

Complete example: order.updated

{
  "event_id": "EVENT#123e4567-e89b-12d3-a456-426614174000",
  "hook_id": "HOOK#2f6d8c1b-5f8f-4b3a-9d52-87a6f3bcd8c2",
  "event_type": "order.updated",
  "data": {
    "order": {
      "id": "1234-1610641025-49201",
      "status": "SUCCEEDED", // 👇 Final state that triggered the event
      "amount": "4490000",
      "created_at": "2025-07-21T22:01:11.318Z",
      "updated_at": "2025-07-22T22:01:13.049Z",
      "fulfilled_at": "2025-07-21T22:01:11.318Z",
      "funding_method": "ORDINARY",
      "type": "TOKENIZE",
      "chain": "POLYGON",
      "public_data": {
        "financial_items": {
          "transfer_amount": "4490000"
        },
        "created_by_user_id": "79768252-b9f5-4582-b8b8-42978849ecaf",
        "deposit_originated_at": "2025-07-21T00:00:00.000Z",
        "destination_wallet_address": "0x03FF28532626Aa54Dd61236dA204b0854534f3D3",
        "mint_and_transfer_transaction": "0x4e9aebcb4aec74cd717dfb5306126c5c1711ebf5f7b263da62e6a5447276f123"
      },
      "activities": [
        {
          "type": "CREATE_ORDER",
          "status": "SUCCEEDED",
          "last_update_at": "2025-07-21T22:01:11.303Z"
        },
        {
          "type": "SETTLE_ORDER",
          "status": "SUCCEEDED",
          "last_update_at": "2025-07-21T22:01:12.654Z"
        },
        {
          "type": "BROADCAST_TRANSACTION",
          "status": "SUCCEEDED",
          "last_update_at": "2025-07-22T22:00:11.708Z"
        },
        {
          "type": "MINT_AND_TRANSFER_TOKENS",
          "status": "SUCCEEDED",
          "last_update_at": "2025-07-22T22:01:12.729Z"
        }
      ]
    }
  },
  "signature": {
    "properties": [
      "order.id",
      "order.status",
      "order.amount"
    ],
    "checksum": "124F3E92EA81EAC6DAB684035557433BA1922A7A47FED49F2001E831B5185C7E"
  },
  "timestamp": 1530291411,
  "sent_at": "2023-11-04T01:35:34.165Z"
}

Handling retries

If your endpoint fails to respond with HTTP 200:

1. The same event will be retried up to 14 times
2. Each retry is a new hook with a different hook_id
3. The event_id remains the same across all retries
4. The timestamp and sent_at fields reflect the current delivery attempt, not the original event time

Example:

• Hook #1: event_id=ABC, hook_id=123, sent_at=2025-01-01T10:00:00Z → Fails
• Hook #2: event_id=ABC, hook_id=456, sent_at=2025-01-01T10:01:00Z → Retry (same event, new hook)

Retry schedule

Attempt	Delay from previous attempt
1	Immediate
2	1 minute
3	2 minutes
4	4 minutes
5	8 minutes
6	16 minutes
7	32 minutes
8	64 minutes (~1 hour)
9	128 minutes (~2 hours)
10	256 minutes (~4 hours)
11	512 minutes (~8 hours)
12	1024 minutes (~16 hours)
13	2048 minutes (~32 hours)
14	4096 minutes (~64 hours)

Total retry window: ~64 hours from first attempt

If all 14 attempts fail, the event is marked as FAILED and no further retries occur.

Next steps

• Verify webhook signatures
• Implement best practices