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.completionevents, including failed orders? - How do I keep my catalog in sync with
product.updateevents? - 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_); 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:
| Event | Triggered when | Body |
|---|---|---|
order.completion | An order has finished processing | status COMPLETED: the order summary. status FAILED: only { id, status } |
product.update | A product in the catalog is added, updated or removed | { product_ |
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
- references/overview.md - Runa webhook concepts, event payloads, delivery rules
- references/setup.md - Add an endpoint in the Svix portal, get the secret, test it
- references/verification.md - Svix verification details, header fallback, manual verifier, timestamp window