Webhooks

A signed POST to your server when a payment confirms on the network. It is the only notification Brykto sends, and the only thing that proves a payment happened.

Setup

1. Open Dashboard > Developer Tools.
2. Enter your webhook URL and save.
3. Copy your webhook secret.

Your URL is checked at delivery time and must be:

• https, not http
• Publicly resolvable. Private, loopback, link-local, reserved and multicast addresses are all refused
• Reachable without a login

The order.paid event

order.paid is the only event. The payload nests everything under data.

{
  "event": "order.paid",
  "timestamp": "2026-08-17T12:04:11.882431+00:00",
  "data": {
    "request_id": "3f9a1c2e-7b4d-4f81-9c22-1a5e6d8b0f33",
    "amount": "49.9",
    "currency": "USD",
    "receive_asset": "USDC",
    "status": "completed",
    "description": "Order 1042",
    "order_id": "1042",
    "customer_id": "cust_88",
    "customer_name": "Jane Smith",
    "rail": "stellar",
    "tx_hash": "a1b2c3d4e5f6...",
    "caller_wallet": "GBXY...",
    "amount_received": "49.9",
    "paid_at": "2026-08-17T12:04:09+00:00",
    "expires_at": "2026-08-17T12:30:00+00:00"
  }
}

amount and amount_received can differ. Brykto accepts a payment within 0.1% for USDC, USDT0 and RLUSD, and within 2% for XLM and XRP.

Headers

Verifying the signature

HMAC-SHA256 over {timestamp}.{body}, keyed with your webhook secret.

import hashlib
import hmac


def verify(body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    signed   = timestamp.encode("utf-8") + b"." + body
    expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

import crypto from "crypto";

export function verify(body, signature, timestamp, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(Buffer.concat([Buffer.from(timestamp + "."), body]))
    .digest("hex");

  const a = Buffer.from(expected);
  const b = Buffer.from(signature || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

<?php
function brykto_verify(string $body, string $signature,
                       string $timestamp, string $secret): bool {
    $expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);
    return hash_equals($expected, $signature);
}

Three things that break verification:

• The timestamp is the one in the header, not the timestamp inside the payload.
• The header value includes the sha256= prefix. Compare the whole value, or strip it from both sides.

Retries

Three attempts, 30 seconds apart. Your endpoint has 10 seconds to return a 2xx.

Reply first and do the slow work afterwards. A handler that sends email before responding will time out and be retried.

webhook_attempts, webhook_delivered_at and webhook_last_error are recorded against the payment.

Replay protection

tx_hash is unique per payment. Store the ones you have handled and ignore repeats.

if db.already_handled(data["tx_hash"]):
    return "", 200

db.mark_handled(data["tx_hash"])
fulfil(data["order_id"])

Without this, a retry after a slow response ships the same order twice.

Security checklist

• Verify the signature on every call, and reject anything that fails
• Use the raw request body
• Ignore any tx_hash you have already handled
• Compare amount against your own record before fulfilling
• Return 2xx quickly, then do the work
• Never fulfil from a browser redirect

Next steps

• Pay-per-access - a full worked example of webhook-gated delivery
• Payment Links API - the request that starts it all