> For the complete documentation index, see [llms.txt](https://developers.unigox.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.unigox.com/basics/webhooks-callbacks.md).

# Webhooks (Callbacks)

## Webhook Delivery

Webhooks are the primary source of order state updates.

Delivery model:

* event type: `order.status.changed`
* transport: HTTPS `POST`
* success condition: any `2xx` response
* signature headers:
  * `X-Unigox-Signature`
  * `X-Unigox-Timestamp`
* user agent: `unigox-webhooks/1.0`

Signature model:

* HMAC-SHA256 over `"<timestamp>.<raw_body>"`
* header format: `sha256=<hex>`
* secret source: your partner `webhook_secret`

Operational behavior from the live dispatcher:

* maximum attempts: `10`
* retry schedule: `1 min`, `5 min`, `15 min`, `1 h`, `6 h`, `12 h`, `24 h`
* once the schedule is exhausted, remaining retries continue at the final `24 h` interval until max attempts is reached
* stale `in_progress` deliveries are recovered back to `pending` after `5 minutes`

Delivery safeguards:

* HTTPS only
* redirects are not followed
* connect/TLS timeout: `3 seconds`
* total request timeout: `10 seconds`
* SSRF protection rejects loopback, private, link-local, and unspecified IPs

Partner guidance:

* de-duplicate by `event_id`
* keep webhook handlers idempotent
* acknowledge quickly, then process asynchronously
* use polling only for recovery and reconciliation

For full webhook request, test, and payload details, see [Webhooks](broken://pages/WlYs2o4Vk0Bunfg6TWmE).