Webhooks

BLOX sends webhook events as HTTP POST requests to a URL that you register. All products use the same envelope, the same signature scheme, and the same delivery policy. The product pages give only the webhook events that BLOX sends and the contents of data.

Register an endpoint

Type	Events
`CHECKOUT`	Checkout events
`PAYOUT`	Payout events
`WALLET`	Wallet events

For each webhook type, the related product must be enabled on your account.

Your signing secret and your API key are independent. If you rotate one, the other does not change.

Envelope

All products use this envelope for all webhook events:

{
  "eventId": "payout.updated:b0e6c2f4-…:SETTLED",
  "event": "payout.updated",
  "webhookType": "PAYOUT",
  "timestamp": "2026-07-16T09:31:05.000Z",
  "data": {}
}

Field	Description
`eventId`	The unique identifier of the event. Use it to process each event one time. Treat it as an opaque string.
`event`	The event name, for example `payout.updated`
`webhookType`	`CHECKOUT`, `PAYOUT`, or `WALLET`
`timestamp`	The time of the event, in ISO 8601 format
`data`	The payload of the event. Its fields change with the product. Refer to the events page of the product.

Headers

Header	Value
`Content-Type`	`application/json`
`X-Blox-Timestamp`	The time when BLOX signed the payload, in Unix seconds
`X-Blox-Signature`	`sha256=` followed by the hex HMAC-SHA256 of `"{timestamp}.{rawBody}"`

Verify the signature

Calculate the HMAC-SHA256 of "{X-Blox-Timestamp}.{rawBody}". Use the whsec_… secret of your endpoint as the key.

Two errors cause the verification to fail, and the failure does not show the cause:

Use the X-Blox-Timestamp header. Do not use the timestamp field in the body. The header is in Unix seconds. The body field is in ISO 8601 format. A signature that you calculate with the body field always fails.
Verify the raw body bytes before you parse the JSON. If you serialize the body again, the bytes change and the signature does not match.

Compare the signatures in constant time. Reject a webhook event if its X-Blox-Timestamp is more than 300 seconds from your server clock.

Delivery policy

	Value
Timeout	10 seconds
Retries	A maximum of 5 attempts. The time between attempts increases exponentially (about 1m, 2m, 4m, 8m).
Redirects	BLOX does not follow redirects. A `3xx` response is a failure.
URL	Must be publicly reachable. Must not resolve to a private or local address.

Return a 2xx response quickly. Do the work after you return the response. After the fifth failed attempt, BLOX does not send the event again. Thus, use webhook events as your primary source of updates. To find the events that you did not receive, also get the status from the API.

Use eventId to process each event one time. BLOX can send the same event more than one time. If BLOX retries a delivery that your server received, you get the same event again. Store each eventId. If an eventId arrives again, do not process the event again.

URL requirements

Must be publicly reachable from the internet
HTTPS is recommended. BLOX currently accepts plain HTTP.
Must not resolve to a private or local network address
BLOX treats redirects (3xx) as failures

Testing

For a local endpoint, use a tunnel (for example, ngrok). Then cause activity in sandbox. For example, create a checkout, create a payout, or make a deposit to the trigger address of a beneficiary.