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, there’s no separate endpoint to retrieve it later. Losing it means you can no longer verify deliveries and have to register a new URL to get a fresh one, see below.

Re-registering a different webhookUrl on the same key keeps the same webhookSecret; only the first registration generates one. 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.

Overview

Guides

API Reference

SDKs & Widget

AI Agents

Settlement Webhooks

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

Register a URL

What gets sent

Verify the signature

What this isn’t