# Guide to Runa Webhooks: Features and Best Practices

[Runa](https://runa.io) is a payouts network for gift cards, prepaid cards and push-to-card payments, all ordered through one API. It sends two kinds of webhook: one when an order finishes processing, which matters if you order asynchronously, and one when a product in the catalogue changes, so you can stop offering a card the moment it becomes unavailable.

We'll look at both events, the one-event-per-endpoint rule and what it means for your routes and secrets, Runa's Svix signing and retry schedule, and how to test without the playground.

## What are Runa webhooks?

Runa delivers webhooks through Svix and manages them in a Svix portal linked from your account. According to Runa's [webhooks reference](https://docs.runa.io/reference/webhooks), each endpoint receives exactly one event type. To get both, you add two endpoints, and each has its own signing secret.

The bodies are bare API resources. An order completion delivers the order; a product update delivers the product's before and after state. There is no envelope and no field naming the event, so your receiver has to know from the endpoint which kind it is handling.

## Runa webhook features

| Feature | Details |
| --- | --- |
| Signature | Standard Webhooks HMAC-SHA256 |
| Signature header | `svix-signature` |
| Body | JSON |
| Delivery platform | Svix |
| Event types | `order.completion`, `product.update` |
| Subscriptions | Exactly one event type per endpoint |
| Event identification | None in the body; use the endpoint |
| Secret | `whsec_`, one per endpoint |
| Timeout | 15 seconds |
| Retries | Immediately, 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h |
| Auto-disable | After 5 days of failed attempts |
| Ordering | Not guaranteed |
| Source IPs | `52.215.16.239`, `54.216.8.72`, `63.33.109.123` |

## Events and payloads

| Event | Triggered When | Common Use Cases |
| --- | --- | --- |
| `order.completion` | An order has finished processing, whether it completed or failed | Fulfil async orders, record order data, alert on failures |
| `product.update` | A product in the catalogue is added, updated or removed (one event per product) | Enable or disable products, refresh pricing and denominations |

Runa's webhook pages and OpenAPI file (API version `2024-02-05`) describe the payload schemas but print no example bodies.

### order.completion

Runa says to use `status` to tell which payload you have. A successful order arrives with `status: "COMPLETED"` and the order summary, whose schema requires `id`, `status`, `created_at`, `payment_method`, `currency`, `total_price` and `total_discount`. A failed order arrives as a stub with just `id` and `status: "FAILED"`. For anything more, such as the reason for a failure, look the order up through the Orders API.

### product.update

| Field | Meaning |
| --- | --- |
| `product_code` | Identifies the product that changed |
| `old_state` / `new_state` | The product before and after: `price_multiplier`, `is_orderable`, and optional `denominations` |
| `timestamp` | UTC ISO 8601 time of the update |

What to do with each change:

| Change | Action |
| --- | --- |
| `is_orderable` becomes `false` | Disable the product; orders for it (or for a removed denomination) are rejected |
| `is_orderable` becomes `true` | Enable the product again |
| `price_multiplier` changes | Update pricing and discounts in your catalogue |

## Setting up Runa webhooks

1. In your Runa account, open the [API section](https://app.runa.io/api-keys) and click **View webhook** to open the portal.
2. Click **Add new endpoint**, enter an HTTPS URL and, optionally, a description.
3. Select one event type, `order.completion` or `product.update`.
4. Create the endpoint and copy its `whsec_` secret from the endpoint page.
5. Repeat for the other event type, ideally with a different URL.

Webhooks don't work in Runa's playground environment. Instead, open the endpoint's **Testing** tab in the portal, choose an event type and click **Send Example**; the result appears in the **Message Attempts** table. If you have no URL yet, the **Use Svix Play** button generates a test URL you can inspect, or you can forward to your laptop with the [Hookdeck CLI](/docs/cli):

```bash
npx hookdeck-cli listen 3000 runa --path /webhooks/runa/orders

```

If your endpoint sits behind a firewall or NAT, allow Runa's three Svix addresses: `52.215.16.239`, `54.216.8.72` and `63.33.109.123`.

**With Hookdeck.** Create two **Runa** sources, one per event type, and register each URL as its own portal endpoint with the matching secret. Hookdeck returns `200` well within Runa's 15-second limit, only takes `POST` requests, and holds back anything with an invalid signature, logging it as failed verification. Separate sources also tell your service which event it is receiving.

## Securing Runa webhooks

Runa's documentation shows Svix's library verifying the `svix-id`, `svix-timestamp` and `svix-signature` headers, and refers to Svix for the details. The signed string is `{svix-id}.{svix-timestamp}.{raw body}`, the HMAC-SHA256 key is the base64-decoded part of the secret after `whsec_`, and the header carries `v1,<base64>` entries. Without the library:

```javascript
const crypto = require('node:crypto');

function decodeBase64(value) {
  if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
  const bytes = Buffer.from(value, 'base64');
  return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
    ? bytes : null;
}

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const prefix = headers['svix-id'] ? 'svix' : 'webhook';
  const id = headers[`${prefix}-id`];
  const timestamp = headers[`${prefix}-timestamp`];
  const signature = headers[`${prefix}-signature`];
  if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
      !/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
  const key = decodeBase64(secret.replace(/^whsec_/, ''));
  if (!key) return false;
  const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
  const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    const received = decodeBase64(candidate);
    if (!received) return false;
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

```

Because the body doesn't name the event, give each portal endpoint its own route and secret:

```javascript
const express = require('express');

// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
  try {
    const value = JSON.parse(rawBody.toString('utf8'));
    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
  } catch {
    return null;
  }
}

const app = express();

app.post('/webhooks/runa/orders', express.raw({ type: '*/*' }), async (req, res) => {
  const secret = process.env.RUNA_ORDERS_WEBHOOK_SECRET;
  if (!secret) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

  const order = parseJsonObject(req.body);
  if (!order) return res.sendStatus(400); // signed, but not a JSON object
  if (!order.id || typeof order.status !== 'string') return res.sendStatus(400);
  try {
    if (order.status === 'COMPLETED') await payouts.fulfil(order.id, order);
    else if (order.status === 'FAILED') await payouts.investigate(order.id);
  } catch {
    return res.sendStatus(503); // not processed, so don't acknowledge
  }
  return res.sendStatus(200);
});

app.post('/webhooks/runa/products', express.raw({ type: '*/*' }), async (req, res) => {
  const secret = process.env.RUNA_PRODUCTS_WEBHOOK_SECRET;
  if (!secret) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

  const payload = parseJsonObject(req.body);
  if (!payload) return res.sendStatus(400); // signed, but not a JSON object
  const { product_code, new_state, timestamp } = payload;
  if (!product_code || !new_state) return res.sendStatus(400);
  try {
    await catalogue.applyIfNewer(product_code, timestamp, new_state);
  } catch {
    return res.sendStatus(503); // not processed, so don't acknowledge
  }
  return res.sendStatus(200);
});

```

`payouts.fulfil` should do nothing for an order ID and status it has already handled. `catalogue.applyIfNewer` should ignore an update older than the last one stored for that `product_code`, since Runa doesn't guarantee order.

The Svix library in Runa's sample rejects timestamps more than five minutes old. Hookdeck applies no tolerance of its own, and it re-sends the original `svix-timestamp` when it retries or replays a message, so the library would reject those once they are five minutes old. Verify without an age check, as above, in services behind Hookdeck.

> **Make Runa webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) answers Runa inside 15 seconds, routes each event type to the right service, and keeps catalogue changes until your service is ready to apply them.

## Runa webhook limitations and pain points

### The body doesn't say what it is

**The Problem:** A shared handler can't tell an order from a product update, and a single secret only verifies one of them.

**Why It Happens:** Payloads are bare resources with no event field, and each endpoint has one event type and its own secret.

**Workarounds:**

* Use a separate route and secret per event type.
* If you must share a URL, try each secret in turn and infer the type from the shape (`product_code` versus `status`).

**How Hookdeck Can Help:** One Hookdeck source per event type keeps the routing explicit, and each [connection](/docs/connections) can deliver to a different service.

### No example payloads, and no playground webhooks

**The Problem:** You can't test against real order or product events before going live.

**Why It Happens:** The docs give schemas but no example bodies, and the playground doesn't send webhooks.

**Workarounds:**

* Use **Send Example** in the portal's Testing tab and save what arrives as fixtures.
* Validate fields defensively, since a `FAILED` order carries only `id` and `status`.

**How Hookdeck Can Help:** Hookdeck records the example events and real ones alike, ready to inspect and replay.

### Out-of-order product updates

**The Problem:** An older catalogue state overwrites a newer one.

**Why It Happens:** Runa doesn't guarantee delivery order, and retries can arrive after later updates.

**Workarounds:**

* Store `timestamp` per `product_code` and discard anything older.

**How Hookdeck Can Help:** Hookdeck records each event's arrival time, which helps you trace ordering problems, but the `timestamp` check stays in your code.

### Endpoints disabled after five days

**The Problem:** A long outage leaves the endpoint disabled and events stop.

**Why It Happens:** After about 28 hours of retries a message is given up, and an endpoint whose attempts all fail for 5 days is disabled.

**Workarounds:**

* Re-enable with **Enable Endpoint** in the portal, then use **Options > Recover Failed Messages** to resend everything since a date.

**How Hookdeck Can Help:** Hookdeck accepts every delivery, so the portal endpoint keeps succeeding, and [retries](/docs/retries) to your service follow your own policy.

## Best practices

### Treat `order.completion` as the async signal

If you place orders in async mode, fulfil only when `order.completion` arrives with `COMPLETED`, and fetch the order for detail on failures.

### Disable products immediately

When `new_state.is_orderable` turns `false`, hide the product or denomination at once; Runa rejects orders for it.

### Deduplicate on `svix-id` and order state

Retries and manual resends repeat the same `svix-id`. For orders, the pair of order `id` and `status` makes a natural business key too. See the [webhook idempotency guide](/webhooks/guides/implement-webhook-idempotency) for storage patterns.

### Answer within 15 seconds

Runa treats slower responses as failures. Queue the work and return `200`.

## Conclusion

Runa's two webhooks cover what a payouts integration needs: knowing when an order is done and keeping the catalogue current. Give each event type its own endpoint, route and secret, check `status` on orders and `timestamp` on products, and respond within 15 seconds.

With [Hookdeck Event Gateway](https://hookdeck.com) in front, each event type gets its own source, and nothing is lost if your service is down for longer than Runa retries. [Get started for free](https://dashboard.hookdeck.com/signup) and send a Runa example event to a Hookdeck source.