Settlement Webhooks

Register a URL and RAVN posts to it whenever a swap made with your key settles, gets refunded, or fails. This is a convenience notification layer on top of /status, not a replacement for it, see What this isn’t before you build on it.

Register a URL

Set webhookUrl on PATCH /v1/keys. It must be https://.

curl -s -X PATCH https://app.ravn.exchange/api/v1/keys \
  -H 'x-api-key: rvn_live_your_key_here' \
  -H 'content-type: application/json' \
  -d '{ "webhookUrl": "https://your-service.example/ravn-webhook" }'

{ "data": { "webhookUrl": "https://your-service.example/ravn-webhook", "webhookSecret": "a1b2c3..." } }

Save webhookSecret immediately. It’s only ever returned from this exact call, and there’s no separate endpoint to retrieve it or rotate it later. Re-registering a different webhookUrl on the same key does not get you a fresh one, see below, so losing it means you can no longer verify deliveries on this key at all.

Re-registering a different webhookUrl on the same key keeps the same webhookSecret; only the first-ever registration on a key generates one. This is deliberate: rotating endpoints shouldn’t also force you to update your signature-verification code. Enterprise keys don’t support webhooks yet and return 404 NOT_FOUND on this field.

What gets sent

When a swap executed with your x-api-key reaches a terminal state, RAVN POSTs this to your URL:

{
  "event": "swap.settled",
  "requestId": "...",
  "partnerId": "...",
  "venue": "mayan",
  "deliveredOut": "...",
  "slippageBps": 10,
  "ts": 1234567890
}

event is one of swap.settled, swap.refunded, or swap.failed. ts is the delivery timestamp, epoch milliseconds. deliveredOut and slippageBps can be null on a venue that doesn’t report them.

Verify the signature

Every request carries an x-ravn-signature header: sha256=<hex>, an HMAC-SHA256 of the exact raw JSON body using your webhookSecret. Verify it against the raw bytes, before you parse the body, not against a re-serialized copy of it.

import { createHmac, timingSafeEqual } from "node:crypto";

function isValidSignature(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

import hashlib
import hmac

def is_valid_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

What this isn’t

This is not a reliable, real-time push system, treat it as a convenience on top of polling.

Deliveries fire from a background settlement job that runs roughly every 5 minutes, so a webhook can lag up to that long behind what /status would already show you.
Delivery is best-effort and fired once. If your endpoint is down, times out, or the request otherwise fails, there is no retry and no way to recover that specific notification, it’s gone.

/status polling remains the only way to get a guaranteed final result. Use webhooks to avoid polling every swap constantly, not as your source of truth for whether one actually completed.

​Register a URL

​What gets sent

​Verify the signature

​What this isn’t

Register a URL

What gets sent

Verify the signature

What this isn’t