Agent skill

Runa Webhooks Skill

Receive and verify Runa webhooks (payouts network for gift cards, prepaid cards and push-to-card, delivered via Svix). Use when setting up Runa webhook handlers, debugging svix-signature verification, or handling order.completion and product.update events.

Install this skill

npx skills add hookdeck/webhook-skills --skill runa-webhooks


Runa is a payouts network for gift cards, prepaid cards and push-to-card. Its webhooks report order completion and product-catalog changes. Endpoints are added in a Svix webhook portal that opens from the API section of your Runa account, and Svix implements Standard Webhooks. Every delivery is an HTTP POST with a JSON body and three signature headers: svix-id, svix-timestamp, and svix-signature.

The body is a bare resource with no envelope and no event-type field. Each endpoint subscribes to exactly one event type (order.completion or product.update), so the endpoint URL identifies the event. A handler that serves several event types on one URL tells them apart by payload shape, as the examples do.

When to Use This Skill

  • How do I receive Runa webhooks?
  • How do I verify Runa webhook signatures (svix-signature)?
  • How do I handle order.completion events, including failed orders?
  • How do I keep my catalog in sync with product.update events?
  • Why is my Runa webhook signature verification failing, or rejecting Hookdeck retries?

Verification (core)

Signed content is {svix-id}.{svix-timestamp}.{raw body}. Svix signs it with HMAC-SHA256 using the base64-decoded secret (the part after whsec_), base64-encodes the result, and sends one or more space-separated v1,<signature> entries. Use the official svix library, which compares in constant time. Read the svix-* headers, and when svix-id is absent fall back to the webhook-* headers (webhook-id, webhook-timestamp, webhook-signature).

import { Webhook } from 'svix'; // svix 2.x is ESM-only

const prefix = req.headers['svix-id'] ? 'svix' : 'webhook';
const id = req.headers[`${prefix}-id`];
const timestamp = req.headers[`${prefix}-timestamp`];
const signature = req.headers[`${prefix}-signature`];
// rawBody: the raw Buffer/string, never re-serialized JSON
new Webhook(process.env.RUNA_WEBHOOK_SECRET).verify(rawBody, {
  'svix-id': id, 'svix-timestamp': timestamp, 'svix-signature': signature,
  'webhook-id': id, 'webhook-timestamp': timestamp, 'webhook-signature': signature,
}); // throws on a bad signature or a timestamp outside the window
const event = JSON.parse(rawBody.toString('utf8')); // parse only after verify passes
from svix.webhooks import Webhook, WebhookVerificationError

wh = Webhook(os.environ["RUNA_WEBHOOK_SECRET"])  # "whsec_..."
wh.verify(raw_body, {"svix-id": id, "svix-timestamp": ts, "svix-signature": sig,
                     "webhook-id": id, "webhook-timestamp": ts, "webhook-signature": sig})

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

The webhook secret is per endpoint and comes from the Svix portal. It starts with whsec_. Keep the full whsec_... value in RUNA_WEBHOOK_SECRET. Handlers fail closed: with the variable unset (or not a whsec_ value) they return 500 instead of accepting anything. Runa's docs show Svix's sample secret (whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw); it is not your secret.

Hookdeck retries and replays hit the 5-minute window

The svix library always enforces a fixed 5-minute timestamp window, and it can't be configured. Hookdeck retries and replays resend the original svix-timestamp, so the library rejects any retry or replay that happens more than 5 minutes after the original delivery. If you verify behind Hookdeck (or replay old events), use the manual verifier in references/verification.md, where the window can be dropped or widened. Deduplicate on the order id (plus status) or on svix-id instead of relying on the timestamp.

Event Types

Runa documents two event types. The body carries no event name, so the examples identify the event from the payload:

EventTriggered whenBody
order.completionAn order has finished processingstatus COMPLETED: the order summary. status FAILED: only { id, status }
product.updateA product in the catalog is added, updated or removed{ product_code, old_state, new_state, timestamp }

For order.completion, the status field tells the two payloads apart (it distinguishes the outcome, not the event). For product.update, delivery order isn't guaranteed: store the timestamp per product_code and discard events older than the last one you saw. Runa creates one event per product, so a bulk change sends many. See references/overview.md for payload fields and delivery rules.

Environment Variables

# Webhook secret for the endpoint, from the Svix portal (starts with whsec_)
RUNA_WEBHOOK_SECRET=whsec_xxxxx

Local Development

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 runa --path /webhooks/runa

Add the tunnel URL as an endpoint in the Svix webhook portal (Runa account > API > View webhook) and copy the endpoint's signing secret into .env. Webhooks aren't available in Runa's playground environment; use the portal's Testing tab to send example events. See references/setup.md.

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →