Webhooks

​

Set up

​

Events

​

Payload

{
  "id": "5c2b1f0e-3a8d-4f6b-9a61-2f7d0c9e4b11",
  "type": "payment.confirmed",
  "apiVersion": "2026-09-25",
  "createdAt": "2026-09-25T03:12:44Z",
  "data": {
    "paymentId": "0b6f2a3c-7d41-4c0e-8e5b-1a9d3f6c2e70",
    "projectId": "9e1d4c7a-2b58-4f3e-a6d0-7c8b5e1f3a29",
    "status": "confirmed",
    "grossAmount": { "value": "100.00", "asset": "USDC" },
    "feeTotal": { "value": "1.50", "asset": "USDC" },
    "netAmount": { "value": "98.50", "asset": "USDC" },
    "chainId": 8453,
    "network": "Base",
    "txHash": "0x…",
    "payerAddress": "0x…",
    "resource": "https://shop.example/checkout/ORDER-8812",
    "description": "Order 8812",
    "createdAt": "2026-09-25T03:12:40Z",
    "settledAt": "2026-09-25T03:12:43Z"
  }
}

​

Verify signatures

1. Build the signed content: {webhook-id}.{webhook-timestamp}.{raw body}. Use the raw body bytes, before any JSON parsing.
2. Take the part of your secret after whsec_ and base64-decode it. That is the HMAC key.
3. Compute HMAC-SHA256 of the signed content and base64-encode it.
4. Accept the request if any v1 value in webhook-signature matches. Use a constant-time compare.
5. Reject timestamps more than 5 minutes from your clock.

import crypto from "node:crypto";

export function verifyPrismWebhook(secret: string, headers: Record<string, string>, rawBody: string): boolean {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest("base64");
  return signatures.split(" ").some((part) => {
    const [version, signature] = part.split(",");
    return version === "v1" && signature.length === expected.length
      && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  });
}

import base64, hashlib, hmac, time

def verify_prism_webhook(secret: str, headers: dict, raw_body: str) -> bool:
    msg_id = headers["webhook-id"]
    timestamp = headers["webhook-timestamp"]
    if abs(time.time() - int(timestamp)) > 300:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    expected = base64.b64encode(
        hmac.new(key, f"{msg_id}.{timestamp}.{raw_body}".encode(), hashlib.sha256).digest()
    ).decode()
    return any(
        part.split(",", 1)[0] == "v1" and hmac.compare_digest(part.split(",", 1)[1], expected)
        for part in headers["webhook-signature"].split(" ")
    )

​

Retries and auto-disable

• Prism tries each event up to 3 times: at once, after 1 minute, and after 5 minutes.
• Only a 2xx response counts as success. Redirects count as failures and are not followed.
• Each call times out after 10 seconds.
• After 3 failed calls in a row, or any 410 Gone, Prism disables the endpoint and shows a banner in Settings → Webhooks. Fix your endpoint, then turn it back on. The reachability test runs again.
• When you turn an endpoint back on, payments confirmed in the last 24 hours that were not sent are delivered once. Older ones are not. Use the payments API to reconcile a longer outage.
• The delivery log shows every event with its status, attempts, and last result. You can resend a Failed or Delivered event, one at a time. A resend keeps the same webhook-id.

​

Delete an endpoint

​

Rotate the secret

​

Best practices

• Return 2xx quickly, then process the event in the background.
• Use webhook-id as an idempotency key.
• After an outage, reconcile with the payments API instead of relying only on webhooks.