Polling with
POST /products/orders/retrieve keeps working. Webhooks are faster and lighter, and the two can be used together: use webhooks as the main path and poll only as a safety net.Set it up
You can do it in the dashboard (API access > Webhooks) or through the API. You need anhttps:// address that answers with a 2xx status within 8 seconds.
1
Create the webhook
whsec_...). It is shown once: store it like a password. Lost it? Create a new one with POST /webhook/secret.2
Send a test
POST /webhook/test sends a webhook.test event to your address and tells you what your server answered.3
Verify and answer
Check the signature (below), save the event, and answer
200. Do the slow work after you have answered."events": ["order.completed", "order.failed"]. Leave it out to receive all of them.
Events
Only final states are sent. An order that is still processing sends nothing; you get one event when it ends.
What you receive
POST with a JSON body and these headers:
order.completed
data is the same order object that GET /products/order/{orderId} returns, plus object and currency. Accounts billed in dollars receive price in USD and "currency": "USD". Top-up events carry the same fields as GET /flexy/status/{id} with "object": "flexy_order".
Verify the signature
Always verify it. Anyone who knows your address could otherwise send you fake deliveries.- Read the raw request body (before any JSON parsing).
- Build the string
{X-Wasmou-Timestamp}.{raw body}. - Compute HMAC-SHA256 of it with your signing secret, as hex.
- Compare with the value after
v1=using a constant-time comparison. - Reject the request if the timestamp is more than 5 minutes old.
Retries and delivery guarantees
- Any
2xxanswer counts as delivered. Anything else (or no answer in 8 seconds) is retried 5 more times: after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. - Redirects are not followed. Use the final address.
- A delivery is at least once. The same event can arrive twice, so store
event.id(ordata.order_idplustype) and ignore repeats. - Events can arrive out of order and can arrive before your own purchase request has returned. Match on
order_id, and if you do not know it yet, answer200and reconcile withGET /products/order/{orderId}. - If 25 deliveries in a row run out of retries, the webhook is switched off and the reason is shown in the dashboard and in
GET /webhook. Fix your server and save the webhook again to switch it back on. Events are only sent from the moment the webhook is on; nothing from the time it was off is replayed, so useGET /ordersto catch up. - Delivery history (last 14 days) is in
GET /webhook/deliveries. Send one again withPOST /webhook/deliveries/{id}/retry.
Security notes
- Only public
https://addresses are accepted. Private, local and internal addresses are refused. - The body can contain a delivered code. Keep your endpoint on HTTPS, do not log bodies in plain text, and keep the secret out of your repository.
- Regenerating your API key does not change your webhook secret, and rotating the secret does not change your API key.