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:
{ "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_idstringUnique identifier for the event (prefixed with EVENT#). Use this for deduplication.
hook_idstringUnique identifier for this delivery attempt (prefixed with HOOK#). Changes with each retry.
event_typestringType of event. See Webhook Events for available types.
dataobjectEvent-specific data containing the complete entity object (see below).
signature.propertiesarrayDeprecated. Fields the legacy checksum covers, fixed per event type. Do not read it from the message to decide what to verify.
signature.checksumstringDeprecated. Legacy SHA256 checksum. Verify the X-Minteo-Signature header instead. See Verifying Signatures.
timestampintegerUnix timestamp (seconds) when this hook was sent.
sent_atstringISO 8601 timestamp when this hook was sent. Same time as timestamp, different format.
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 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} |
Complete payload examples
- order.updated
- payout.updated
- payout.item.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"}{ "event_id": "EVENT#a1b2c3d4-e5f6-7890-abcd-ef1234567890", "hook_id": "HOOK#f9e8d7c6-b5a4-3210-fedc-ba0987654321", "event_type": "payout.updated", "data": { "payout": { "id": "d5e5262c-5697-408d-bb9b-48c3cf8c2f89", "status": "FULFILLED", "fee_type": "DEDUCTED_FROM_ITEM_AMOUNT", "fee_amount": "700", "transfer_amount": "20000", "refunded_amount": null, "status_code": null, "origin_source_id": "d0866d0f-7532-44bc-9466-126764682a0b", "public_data": { "creator_type": "SYSTEM", "creator_identifier": "pKwqg9A7F832CAIX", "deposit_wallet_address": "0x6f2D66cF59Cf6C1c2609f0127c91A480020dC2fd" }, "activities": [ { "type": "AWAIT_PROCESSING", "status": "SUCCEEDED", "last_update_at": "2025-01-15T10:00:00.000Z" }, { "type": "AWAIT_VALIDATIONS", "status": "SUCCEEDED", "last_update_at": "2025-01-15T10:00:05.000Z" }, { "type": "AWAIT_DISBURSEMENT", "status": "SUCCEEDED", "last_update_at": "2025-01-15T10:05:00.000Z" } ], "created_at": "2025-01-15T10:00:00.000Z", "updated_at": "2025-01-15T10:05:00.000Z", "finished_at": "2025-01-15T10:05:00.000Z" } }, "signature": { "properties": ["payout.id", "payout.status", "payout.transfer_amount"], "checksum": "A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2" }, "timestamp": 1705312200, "sent_at": "2025-01-15T10:05:00.000Z"}{ "event_id": "EVENT#b2c3d4e5-f6a7-8901-bcde-f12345678901", "hook_id": "HOOK#c3d4e5f6-a7b8-9012-cdef-123456789012", "event_type": "payout.item.updated", "data": { "payout_item": { "id": "e8f9a0b1-c2d3-4e5f-6a7b-8c9d0e1f2a3b", "payout_id": "d5e5262c-5697-408d-bb9b-48c3cf8c2f89", "status": "SUCCEEDED", "status_code": null, "amount": "20000", "token": "COPM", "full_name": "John Doe", "legal_identifier_type": "CC", "legal_identifier": "123456789", "country_iso": "CO", "network": "BANK", "bank_account_details": { "bank_name": "BANCO_FALABELLA", "type": "SAVINGS", "number": "2109309321" }, "created_at": "2025-01-15T10:00:00.000Z", "updated_at": "2025-01-15T10:05:00.000Z" } }, "signature": { "properties": ["payout_item.id", "payout_item.status", "payout_item.amount"], "checksum": "D4E5F6A7B8C9D4E5F6A7B8C9D4E5F6A7B8C9D4E5F6A7B8C9D4E5F6A7B8C9D4E5" }, "timestamp": 1705312200, "sent_at": "2025-01-15T10:05:00.000Z"}Handling retries
If your endpoint fails to respond with HTTP 200:
- The same event will be delivered up to 17 times (the first attempt plus 16 retries)
- Each retry is a new hook with a different
hook_id - The
event_idremains the same across all retries - The
timestampandsent_atfields 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
| Attempt | Delay from previous attempt | Time since first attempt |
|---|---|---|
| 1 | Immediate | — |
| 2 | 10 seconds | 10 seconds |
| 3 | 20 seconds | 30 seconds |
| 4 | 40 seconds | ~1 minute |
| 5 | 1 minute | ~2 minutes |
| 6 | 2 minutes | ~4 minutes |
| 7 | 4 minutes | ~8 minutes |
| 8 | 8 minutes | ~16 minutes |
| 9 | 16 minutes | ~32 minutes |
| 10 | 32 minutes | ~1 hour |
| 11 | 64 minutes (~1 hour) | ~2 hours |
| 12 | 128 minutes (~2 hours) | ~4 hours |
| 13 | 256 minutes (~4 hours) | ~8.5 hours |
| 14 | 512 minutes (~8.5 hours) | ~17 hours |
| 15 | 1024 minutes (~17 hours) | ~34 hours |
| 16 | 2048 minutes (~34 hours) | ~2.8 days |
| 17 | 4096 minutes (~2.8 days) | ~5.7 days |
Total retry window: ~5.7 days from first attempt
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.