Skip to main content
A webhook is an HTTPS address on your server. Wasmou calls it every time one of your orders reaches a final state, so you can deliver the code to your customer the moment it is ready.
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 an https:// address that answers with a 2xx status within 8 seconds.
1

Create the webhook

The answer contains your signing secret (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.
To receive only some events, send "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.
  1. Read the raw request body (before any JSON parsing).
  2. Build the string {X-Wasmou-Timestamp}.{raw body}.
  3. Compute HMAC-SHA256 of it with your signing secret, as hex.
  4. Compare with the value after v1= using a constant-time comparison.
  5. Reject the request if the timestamp is more than 5 minutes old.

Retries and delivery guarantees

  • Any 2xx answer 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 (or data.order_id plus type) 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, answer 200 and reconcile with GET /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 use GET /orders to catch up.
  • Delivery history (last 14 days) is in GET /webhook/deliveries. Send one again with POST /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.