Skip to main content

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-Minteo-Signature: t=<timestamp>,v1=<signature>
X-Hook-Checksum: <checksum_value>

Verify X-Minteo-Signature against the raw request body before you parse it. See Verifying Signatures. X-Hook-Checksum is deprecated.

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:

WEBHOOK PAYLOAD
{
"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​

event_idstring

Unique identifier for the event (prefixed with EVENT#). Use this for deduplication.

hook_idstring

Unique identifier for this delivery attempt (prefixed with HOOK#). Changes with each retry.

event_typestring

Type of event. See Webhook Events for available types.

dataobject

Event-specific data containing the complete entity object (see below).

signature.propertiesarray

Deprecated. Fields the legacy checksum covers, fixed per event type. Do not read it from the message to decide what to verify.

signature.checksumstring

Deprecated. Legacy SHA256 checksum. Verify the X-Minteo-Signature header instead. See Verifying Signatures.

timestampinteger

Unix timestamp (seconds) when this hook was sent.

sent_atstring

ISO 8601 timestamp when this hook was sent. Same time as timestamp, different format.

info

X-Minteo-Signature signs the whole body and is the signature to verify. The signature object and the X-Hook-Checksum header (same value as signature.checksum) are deprecated and will be removed on a date Minteo will announce.

Data field structure​

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

Event TypeData FieldEquivalent API Response
order.updateddata.orderSame as GET /orders/{id}
payout.updateddata.payoutSame as GET /payouts/{id}
payout.item.updateddata.payout_itemSame as GET /payouts/{payout_id}/items/{item_id}

Complete payload examples​

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",
"amount": "4490000",
"type": "TOKENIZE",
"chain": "POLYGON",
"created_at": "2025-07-21T22:01:11.318Z",
"updated_at": "2025-07-22T22:01:13.049Z",
"public_data": {
"financial_items": {
"transfer_amount": "4490000"
},
"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 delivered up to 17 times (the first attempt plus 16 retries)
  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:00:10Z → Retry (same event, new hook)

Retry schedule​

AttemptDelay from previous attemptTime since first attempt
1Immediate—
210 seconds10 seconds
320 seconds30 seconds
440 seconds~1 minute
51 minute~2 minutes
62 minutes~4 minutes
74 minutes~8 minutes
88 minutes~16 minutes
916 minutes~32 minutes
1032 minutes~1 hour
1164 minutes (~1 hour)~2 hours
12128 minutes (~2 hours)~4 hours
13256 minutes (~4 hours)~8.5 hours
14512 minutes (~8.5 hours)~17 hours
151024 minutes (~17 hours)~34 hours
162048 minutes (~34 hours)~2.8 days
174096 minutes (~2.8 days)~5.7 days

Total retry window: ~5.7 days from first attempt

Retries start after 10 seconds

The first three retries come 10, 20 and 40 seconds after the previous attempt, so a short outage of your endpoint is retried within about a minute. Make sure your endpoint and its rate limits can take these early retries, and keep deduplicating by event_id.

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

Next steps​