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.