Agent skill

Revolut Webhooks Skill

Receive and verify Revolut Merchant webhooks. Use when setting up Revolut webhook handlers, debugging Revolut-Signature verification, or handling order and payment events like ORDER_COMPLETED, ORDER_AUTHORISED, or ORDER_PAYMENT_DECLINED.

Install this skill

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

When to Use This Skill

How do I receive Revolut Merchant webhooks?
How do I verify Revolut webhook signatures (the Revolut-Signature header)?
How do I handle ORDER_COMPLETED or ORDER_PAYMENT_DECLINED events?
Why is my Revolut webhook signature verification failing?
How do I set up a Revolut webhook endpoint via the Merchant API?

Verification (core)

Revolut signs each webhook with HMAC-SHA256 (hex-encoded) using your webhook signing secret (wsk_…, returned when you create the webhook via the Merchant API). There is no official SDK webhook helper, so verify manually.

The signed payload is v1.{Revolut-Request-Timestamp}.{raw body} — period-separated, using the raw request body (re-serialized JSON breaks the signature). The Revolut-Signature header holds v1=<hex> and may carry multiple comma-separated signatures during secret rotation — accept if any matches.

const crypto = require('crypto');

function verifyRevolutSignature(rawBody, timestamp, signatureHeader, secret) {
  if (!timestamp || !signatureHeader) return false;

  // Reject stale timestamps (± 5 min). Header is a UNIX timestamp in ms.
  const ts = Number(timestamp);
  const tsMs = timestamp.length <= 10 ? ts * 1000 : ts; // tolerate seconds or ms
  if (!Number.isFinite(ts) || Math.abs(Date.now() - tsMs) > 5 * 60 * 1000) return false;

  const expected = 'v1=' + crypto
    .createHmac('sha256', secret)
    .update(`v1.${timestamp}.${rawBody}`)
    .digest('hex');

  // Header may hold multiple signatures during rotation — accept any match.
  return signatureHeader.split(',').some((sig) => {
    const a = Buffer.from(sig.trim());
    const b = Buffer.from(expected);
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
}

For complete handlers with route wiring, event dispatch, and tests, see:
examples/express/
examples/nextjs/
examples/fastapi/

Common Event Types

Event	Description
`ORDER_COMPLETED`	Order fully paid and completed
`ORDER_AUTHORISED`	Payment authorised (funds held, not yet captured)
`ORDER_CANCELLED`	Order cancelled
`ORDER_PAYMENT_AUTHENTICATED`	Customer completed payment authentication (e.g. 3DS)
`ORDER_PAYMENT_DECLINED`	Payment declined by the issuer or Revolut
`ORDER_PAYMENT_FAILED`	Payment failed due to a processing error

Payload shape (order events):

{
  "event": "ORDER_COMPLETED",
  "order_id": "6516e61c-d279-a454-a837-bc52ce55ed49",
  "merchant_order_ext_ref": "Order #2937"
}

For the full event reference, see Revolut webhooks documentation.

Environment Variables

REVOLUT_SIGNING_SECRET=wsk_xxxxx   # Signing secret returned when the webhook is created

Local Development

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

Reference Materials

references/overview.md - Revolut webhook concepts and events
references/setup.md - Create webhooks via the Merchant API, get the signing secret
references/verification.md - Signature verification details and gotchas