> ## Documentation Index
> Fetch the complete documentation index at: https://gateway.wasmou.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Get a signed message on your own server when an order is delivered, fails or is refunded. No polling.

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.

> [!NOTE]
>
> 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**

```bash theme={"dark"}
curl -X PUT https://api.wasmou.net/api/webhook \
  -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://your-site.com/wasmou-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

| Event | When |
| - | - |
| `order.completed` | A code or top-up was delivered. `data.key` holds the code when there is one. |
| `order.failed` | The order could not be fulfilled. The amount is back in your wallet. |
| `order.refunded` | The order was refunded to your wallet. |
| `order.canceled` | A manual order was canceled. The amount is back in your wallet. |
| `flexy.completed` | A mobile top-up (Flexy) succeeded. |
| `flexy.failed` | A mobile top-up failed and was refunded. |
| `webhook.test` | Sent only when you press **Send test** or call `POST /webhook/test`. |

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:

| Header | Meaning |
| - | - |
| `X-Wasmou-Event` | The event type, for example `order.completed`. |
| `X-Wasmou-Delivery` | Id of this delivery. The same id is repeated on every retry. |
| `X-Wasmou-Timestamp` | Unix time in seconds when this attempt was signed. |
| `X-Wasmou-Signature` | `v1=` followed by the HMAC-SHA256 signature (hex). |

```json order.completed theme={"dark"}
{
  "id": "evt_6f1c2a3e-8d42-4f0e-9a51-0c7b2e6d9a10",
  "type": "order.completed",
  "api_version": "2026-11-18",
  "created_at": "2026-11-18T10:21:05+00:00",
  "data": {
    "object": "order",
    "order_id": "1794994375667035576",
    "product_name": "Steam Wallet (US)",
    "variant_name": "20 USD",
    "status": "completed",
    "key": "XXXX-XXXX-XXXX",
    "has_key": true,
    "activation": { "brand": "Steam", "url": "https://store.steampowered.com/account/redeemwalletcode", "steps": ["..."], "region": "US" },
    "price": 5190.0,
    "currency": "DZD",
    "created_at": "2026-11-18T10:20:58+00:00",
    "purchase_timestamp": "2026-11-18T10:20:58+00:00"
  }
}
```

`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.

```js Node.js (Express) theme={"dark"}
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.WASMOU_WEBHOOK_SECRET;

app.post("/wasmou-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const ts = req.header("X-Wasmou-Timestamp");
  const sig = (req.header("X-Wasmou-Signature") || "").replace("v1=", "");
  const expected = crypto.createHmac("sha256", SECRET).update(`${ts}.${req.body}`).digest("hex");

  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  const valid = sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
  if (!fresh || !valid) return res.sendStatus(400);

  const event = JSON.parse(req.body);
  // save event.id first; ignore it if you already have it
  if (event.type === "order.completed") {
    const { order_id, key } = event.data;
    // deliver `key` to your customer
  }
  res.sendStatus(200);
});
```

```php PHP theme={"dark"}
<?php
$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_WASMOU_TIMESTAMP'] ?? '';
$sig = str_replace('v1=', '', $_SERVER['HTTP_X_WASMOU_SIGNATURE'] ?? '');
$expected = hash_hmac('sha256', $ts . '.' . $raw, getenv('WASMOU_WEBHOOK_SECRET'));

if (abs(time() - (int) $ts) > 300 || !hash_equals($expected, $sig)) {
    http_response_code(400);
    exit;
}

$event = json_decode($raw, true);
if ($event['type'] === 'order.completed') {
    $orderId = $event['data']['order_id'];
    $key     = $event['data']['key'];
    // deliver $key to your customer
}
http_response_code(200);
```

```python Python (Flask) theme={"dark"}
import hashlib, hmac, os, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["WASMOU_WEBHOOK_SECRET"].encode()

@app.post("/wasmou-webhook")
def wasmou_webhook():
    raw = request.get_data()
    ts = request.headers.get("X-Wasmou-Timestamp", "")
    sig = request.headers.get("X-Wasmou-Signature", "").removeprefix("v1=")
    expected = hmac.new(SECRET, f"{ts}.".encode() + raw, hashlib.sha256).hexdigest()

    if abs(time.time() - int(ts or 0)) > 300 or not hmac.compare_digest(sig, expected):
        abort(400)

    event = request.get_json()
    if event["type"] == "order.completed":
        order_id, key = event["data"]["order_id"], event["data"]["key"]
        # deliver key to your customer
    return "", 200
```

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.