Webhooks

​

Register a URL

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

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

​

The payload

{
  "event": "swap.settled",
  "swapId": "…",
  "requestId": "…",
  "partnerId": "…",
  "venue": "mayan",
  "deliveredOut": "18921340",
  "slippageBps": 10,
  "ts": 1750000000000
}

• event: swap.settled, swap.refunded or swap.failed. Each swap gets one.
• swapId: the swapId /execute returned. requestId is the same value.
• deliveredOut and slippageBps can be null when the venue doesn’t report them.
• ts: delivery time, epoch milliseconds.

​

Delivery

• Any 2xx within 5 seconds counts as delivered. Otherwise it’s retried 5, 20, 45, 80 minutes later and so on, for a day, then dropped.
• It can arrive twice. Deduplicate on swapId and event.
• Webhooks come from a job that runs about every 5 minutes, so they lag /status by up to that. A swap whose fee RAVN is still confirming can take up to a day.

​

Verify the signature

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 "")