Webhooks

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

API-key caller restrictions do not affect outgoing webhook delivery. The webhook IP allowlist, if configured, restricts destination addresses. See API caller IPs and Cloudflare.

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.

Limits for new accounts

Until one of the businesses on your login has received a confirmed live payment or completed a confirmed live top-up, the login can hold at most 3 active webhook endpoints across all its businesses, in live and test mode together, and can use Send test at most 10 times in a rolling 24 hours. The platform operator can change both numbers. Once any business on the login has live activity, neither limit applies, and existing endpoints are never removed.

Suspended and closed accounts

No webhooks are delivered for a business that is suspended or closed. New events create no delivery, and a delivery that was already waiting for a retry is held instead of sent. A held delivery is marked exhausted once it is more than 48 hours overdue. If the suspension is lifted before then, held deliveries resume on their retry schedule.

Webhook URL rules

NoHoldPay checks every webhook URL when you save it: when you create an API key with a webhook, when you add a webhook to a key, and when you edit a webhook's URL. A URL that breaks a rule is refused with a 422 VALIDATION_ERROR whose message starts with Webhook URL invalid:, and nothing is saved.

Scheme and port

You can leave the port out or write the default explicitly (https://hooks.example-shop.com:443/nhp is fine). Ports such as 3000, 8080 or 8443 are refused, and so are padded spellings such as :0443. If your receiver runs on another port, put it behind a reverse proxy or load balancer that listens on 443.

These scheme and port rules also apply to every delivery. If your endpoint answers with a redirect (307 or 308), the new location must follow the same scheme and port rules or the delivery fails. An endpoint saved before these rules existed on another port stops receiving deliveries until you change its URL to use the default port. Its failed deliveries show Destination is blocked by outbound network policy.

The host must be a domain name

Use a public domain name that you control, in both live and test mode:

• No IP addresses. https://203.0.113.10/webhook and https://[2001:db8::1]/webhook are refused. Shorthand or numeric forms of an address (for example http://2130706433/) are refused too. Point a DNS record at your server and use that name.
• No reserved or private names. Names under .test, .example, .invalid, .localhost, .local, .onion, .alt, .internal and .arpa (including home.arpa) are refused, as are example.com, example.net and example.org and their subdomains. These names are reserved for documentation, testing or private networks and cannot receive webhooks from the internet.
• A public top-level domain. The name must end in a top-level domain that is delegated on the public internet, such as .com, .io or .co.uk. Private suffixes such as .corp, .lan or .home are refused.
• The name must exist in DNS. A name that does not exist, or that has no address records, is refused when you save it. If DNS is temporarily unavailable, the URL is accepted.
• The name must resolve to a public address. A name whose address is private, loopback or link-local is refused.

Services that are not accepted

Some public services are refused because webhook payloads sent to them would be exposed to others, or because they exist to point a public name at a private address:

• Wildcard DNS and DNS rebinding services (for example nip.io, sslip.io, lvh.me and localtest.me) and out-of-band security testing services are refused in both live and test mode.
• Public request inspection services (for example webhook.site, Pipedream RequestBin, Beeceptor, Request Catcher, PostBin and smee.io) are accepted for test-mode keys only. They are useful while you build an integration, but anyone who has the URL can read what is sent to it, so they are refused for live webhooks. Before you go live, point your live key's webhook at a receiver you control.

The platform operator can also refuse additional domains. When a URL is refused for any of these reasons, the message is URL host is not allowed for webhooks.

If saving fails with 503

If the response is 503 SERVICE_UNAVAILABLE with the message Webhook URL could not be checked right now. Please try again shortly., nothing was saved. Retry the request after a short wait.

Error messages

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.