Webhooks

NoHoldPay sends a POST request to your endpoint when a payment changes state. Each request is signed. Your endpoint returns 2xx to acknowledge.

Setup

Webhook endpoints are configured per API key. The Webhooks page in the dashboard is a read-only inspector for delivery history. The create/edit surface lives on the API Keys page.

Each API key has its own webhook endpoint and its own secret. To rotate the secret later, click Rotate secret on the same panel. The old secret keeps signing deliveries alongside the new one for a 24-hour grace window (you will see two v1= values in the signature header), then stops verifying.

Event format

Every delivery is a JSON POST with the body:

{
  "id": "evt_8f7c3a1d-4b2e-49ad-b1e7-3c19f0e0b9d2",
  "event": "payment.confirmed",
  "created_at": "2026-05-14T12:00:00Z",
  "data": { ... }
}

Headers sent on every delivery:

The platform's HTTP client uses a 30-second timeout per attempt. If your endpoint hasn't responded with 2xx headers in 30 seconds, the attempt fails and is queued for retry.

Verify the signature

X-Webhook-Signature: t=1715688000,v1=a3f9...

During a secret rotation you may see multiple v1= values separated by commas. Accept the delivery if any one matches.

Verification steps

Example: Node.js

import { createHmac, timingSafeEqual } from "crypto";

function verify(secret: string, rawBody: Buffer, header: string): boolean {
  const tMatch = header.match(/t=(\d+)/);
  const v1Matches = header.match(/v1=([a-f0-9]+)/g) ?? [];
  if (!tMatch || v1Matches.length === 0) return false;

  const t = tMatch[1];
  const v1s = v1Matches.map((s) => s.slice(3));

  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest("hex");

  return v1s.some((v) => {
    try {
      return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(v, "hex"));
    } catch {
      return false;
    }
  });
}

Retry schedule

If your endpoint returns a non-2xx status, times out (30 seconds), or rejects the TCP connection, delivery is retried on this schedule:

Each delay has +/-25% random jitter. After the 9th total attempt fails (the initial delivery plus 8 retries, about 35 hours of runway after the first failure), the delivery is marked exhausted and no further retries fire. The delivery log in the dashboard shows each delivery's latest attempt: the attempt counter, the most recent status code and response body (truncated to 1 KiB), and the next retry time.

Permanent client errors (4xx codes that signal the request is wrong) skip retries by default. 408, 425, and 429 are treated as transient and retry on the normal ladder.

Event reference

Payment events

Invoice events

Tips

• Return 200 as fast as possible. Do the work in a background queue.
• Return 200 for events you do not handle. The retry schedule treats any non-2xx as failure.
• Always deduplicate on the id field. The retry ladder can re-deliver the same event for about 35 hours after the first attempt - keep IDs for 48 hours to be safe.
• The delivery log in the dashboard shows the exact request body that was signed and the latest response body (truncated to 1 KiB) for debugging.