---
title: "Order status callback"
method: POST
path: "orderStatus"
---

# Order status callback

`POST orderStatus` (webhook)

When an order reaches a terminal status (`delivered`, `failed`,
`reversed`, `expired`) we `POST` this event to your `callback_url`.

Verify authenticity with the `X-Faas-Signature` header — it's the
hex `HMAC-SHA256` of the **exact raw request body** under your webhook
secret (the standard Stripe/GitHub signing scheme). Respond `2xx` to
acknowledge; non-2xx is retried with exponential backoff, then
dead-lettered. The body (and signature) are stable across retries.

**Delivery constraints.** Your endpoint must respond within **5 seconds**
(connect + headers + body timeout each). HTTP redirects are not followed —
the `callback_url` must be the final destination. A timeout or non-2xx
response triggers the retry/dead-letter path exactly as a connection error
would; it never blocks order processing.

**Secret rotation (rollover).** During the grace window after you rotate
your webhook secret, this header may carry **multiple comma-separated
signatures** (the new and the previous secret). Treat the header as a
comma-separated list and accept the request if **any** entry matches your
secret — so you can switch from the old secret to the new one at any point
in the window without dropping a webhook. Outside a rotation it is a single
signature, so naive single-value verification keeps working day to day.

## Headers

- `X-Faas-Signature` string, required

## Payload

- object
  - `order_id` string, uuid, required
  - `status` 'delivered' | 'failed' | 'reversed' | 'expired', required
  - `failure_reason` string, nullable — Why a non-`delivered` order ended where it did — `underpaid` / `overpaid` (amount mismatch → `failed`, funds reversed), `no_memo` / `wrong_memo` (an unmatched payment with a missing / unrecognised memo → `failed`, funds reversed to the sender), `undeliverable` (`reversed`, funds reversed), or `expired` (no payment within the window). Null on `delivered`. See **Reversals & delivery** above for the full meaning of each.
  - `purchase_tx` string, nullable
  - `reversal_tx` string, nullable

## Acknowledgement `200`

Acknowledged. Any 2xx stops retries.

---

[API](https://skmtc.net/mystars/apis/mystars-faas-fulfilment-api.md) · [All operations](https://skmtc.net/mystars/apis/mystars-faas-fulfilment-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mystars/mystars-faas-fulfilment-api/revisions/3c24cb3dfa12/schema)