Gareth Wilson Gareth Wilson

Guide to Runa Webhooks: Features and Best Practices

Published


Runa 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, 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

FeatureDetails
SignatureStandard Webhooks HMAC-SHA256
Signature headersvix-signature
BodyJSON
Delivery platformSvix
Event typesorder.completion, product.update
SubscriptionsExactly one event type per endpoint
Event identificationNone in the body; use the endpoint
Secretwhsec_, one per endpoint
Timeout15 seconds
RetriesImmediately, 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h
Auto-disableAfter 5 days of failed attempts
OrderingNot guaranteed
Source IPs52.215.16.239, 54.216.8.72, 63.33.109.123

Events and payloads

EventTriggered WhenCommon Use Cases
order.completionAn order has finished processing, whether it completed or failedFulfil async orders, record order data, alert on failures
product.updateA 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

FieldMeaning
product_codeIdentifies the product that changed
old_state / new_stateThe product before and after: price_multiplier, is_orderable, and optional denominations
timestampUTC ISO 8601 time of the update

What to do with each change:

ChangeAction
is_orderable becomes falseDisable the product; orders for it (or for a removed denomination) are rejected
is_orderable becomes trueEnable the product again
price_multiplier changesUpdate pricing and discounts in your catalogue

Setting up Runa webhooks

  1. In your Runa account, open the API section 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:

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:

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:

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 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 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 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 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 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 and send a Runa example event to a Hookdeck source.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.