Webhook overview

curl "$STABYL_BASE_URL/partner/webhooks" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $STABYL_API_KEY" \
  -d '{
    "url": "https://partner.example.com/stabyl/events",
    "description": "Stabyl event receiver",
    "enabled": true,
    "event_types": [
      "deposit.action_required",
      "deposit.success",
      "deposit.failed",
      "withdrawal.success",
      "withdrawal.partial",
      "withdrawal.failed"
    ]
  }'

{
  "status": "success",
  "data": {
    "webhook": {
      "id": "01980d95-5537-76aa-88a8-ad59117632ef",
      "url": "https://partner.example.com/stabyl/events",
      "description": "Stabyl event receiver",
      "status": "enabled",
      "event_types": [
        "deposit.action_required",
        "deposit.success",
        "deposit.failed",
        "withdrawal.success",
        "withdrawal.partial",
        "withdrawal.failed"
      ],
      "secret_version": 1,
      "created_at": "2026-07-17T11:00:00Z",
      "updated_at": "2026-07-17T11:00:00Z"
    },
    "secret": "whsec_<shown-once>"
  }
}

# List endpoints
curl "$STABYL_BASE_URL/partner/webhooks" \
  -H "X-Api-Key: $STABYL_API_KEY"

# Replace the URL, description, enabled state, and complete subscription list
curl "$STABYL_BASE_URL/partner/webhooks/$STABYL_WEBHOOK_ID" \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $STABYL_API_KEY" \
  -d '{
    "url": "https://partner.example.com/stabyl/events",
    "description": "Stabyl event receiver",
    "enabled": true,
    "event_types": ["deposit.success", "withdrawal.success", "withdrawal.partial", "withdrawal.failed"]
  }'

# Rotate the signing secret; store the new secret from this response
curl "$STABYL_BASE_URL/partner/webhooks/$STABYL_WEBHOOK_ID/secret/rotate" \
  -X POST \
  -H "X-Api-Key: $STABYL_API_KEY"

webhook-id: <stable event ID>
webhook-timestamp: <Unix seconds>
webhook-signature: v1,<base64 HMAC> [v1,<base64 HMAC>]
x-stabyl-delivery-id: <stable endpoint delivery ID>
x-stabyl-event-type: <event type>
x-stabyl-delivery-attempt: <logical attempt number>

webhook-id + "." + webhook-timestamp + "." + raw request body

import crypto from "node:crypto";
import express from "express";

function decodeBase64(value) {
  if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
    throw new Error("invalid base64");
  }
  const decoded = Buffer.from(value, "base64");
  if (decoded.toString("base64") !== value) throw new Error("non-canonical base64");
  return decoded;
}

function verifyStabylWebhook(rawBody, headers, secret, toleranceSeconds = 300) {
  const webhookId = headers["webhook-id"];
  const timestampText = headers["webhook-timestamp"];
  const signatureHeader = headers["webhook-signature"];
  if (!webhookId || !/^\d+$/.test(timestampText ?? "") || !signatureHeader) {
    throw new Error("missing webhook headers");
  }

  const timestamp = Number(timestampText);
  const now = Math.floor(Date.now() / 1000);
  if (!Number.isSafeInteger(timestamp) || Math.abs(now - timestamp) > toleranceSeconds) {
    throw new Error("stale webhook");
  }
  if (!secret.startsWith("whsec_")) throw new Error("invalid secret");
  const key = decodeBase64(secret.slice(6));
  if (key.length !== 32) throw new Error("invalid secret");

  const expected = crypto
    .createHmac("sha256", key)
    .update(webhookId, "utf8")
    .update(".")
    .update(timestampText, "utf8")
    .update(".")
    .update(rawBody)
    .digest();

  const valid = signatureHeader.split(/\s+/).some((candidate) => {
    const comma = candidate.indexOf(",");
    if (comma < 0 || candidate.slice(0, comma) !== "v1") return false;
    try {
      const supplied = decodeBase64(candidate.slice(comma + 1));
      return supplied.length === expected.length && crypto.timingSafeEqual(supplied, expected);
    } catch {
      return false;
    }
  });
  if (!valid) throw new Error("invalid webhook signature");

  return { webhookId, event: JSON.parse(rawBody.toString("utf8")) };
}

const app = express();
app.post("/stabyl-webhooks", express.raw({ type: "application/json" }), async (req, res) => {
  const { webhookId, event } = verifyStabylWebhook(
    req.body,
    req.headers,
    process.env.STABYL_WEBHOOK_SECRET,
  );

  // Keep this insert and your business change in one database transaction.
  // webhook-id must have a unique constraint so a duplicate performs no work.
  await db.transaction(async (tx) => {
    const firstDelivery = await tx.insertWebhookInboxIfAbsent(webhookId);
    if (firstDelivery) await applyEventInSameTransaction(tx, event);
  });
  res.sendStatus(204);
});

import base64
import binascii
import hashlib
import hmac
import json
import time

from fastapi import FastAPI, Header, Request, Response


def verify_stabyl_webhook(
    raw_body: bytes,
    webhook_id: str,
    timestamp_text: str,
    signature_header: str,
    secret: str,
    tolerance_seconds: int = 300,
):
    if not timestamp_text.isascii() or not timestamp_text.isdigit():
        raise ValueError("invalid timestamp")
    timestamp = int(timestamp_text)
    if abs(int(time.time()) - timestamp) > tolerance_seconds:
        raise ValueError("stale webhook")
    if not secret.startswith("whsec_"):
        raise ValueError("invalid secret")

    key = base64.b64decode(secret.removeprefix("whsec_"), validate=True)
    if len(key) != 32:
        raise ValueError("invalid secret")
    signed = webhook_id.encode() + b"." + timestamp_text.encode() + b"." + raw_body
    expected = hmac.new(key, signed, hashlib.sha256).digest()

    valid = False
    for candidate in signature_header.split():
        try:
            version, encoded = candidate.split(",", 1)
            supplied = base64.b64decode(encoded, validate=True)
        except (ValueError, binascii.Error):
            continue
        if version == "v1" and hmac.compare_digest(supplied, expected):
            valid = True
    if not valid:
        raise ValueError("invalid webhook signature")
    return json.loads(raw_body), webhook_id


app = FastAPI()


@app.post("/stabyl-webhooks")
async def receive_webhook(
    request: Request,
    webhook_id: str = Header(alias="webhook-id"),
    webhook_timestamp: str = Header(alias="webhook-timestamp"),
    webhook_signature: str = Header(alias="webhook-signature"),
):
    raw_body = await request.body()
    event, event_id = verify_stabyl_webhook(
        raw_body,
        webhook_id,
        webhook_timestamp,
        webhook_signature,
        STABYL_WEBHOOK_SECRET,
    )

    # Use a unique webhook_id inbox row and apply the business change in the
    # same transaction. A duplicate then commits no second side effect.
    async with db.transaction() as tx:
        first_delivery = await tx.insert_webhook_inbox_if_absent(event_id)
        if first_delivery:
            await apply_event_in_same_transaction(tx, event)
    return Response(status_code=204)