Why am I not receiving webhook events?

If your endpoint isn't getting Bead's POST requests, walk through the checklist below—90 % of "missing webhook" cases trace back to one of these items.

1 — Endpoint health checklist

Check	What to verify	How
URL correct?	Exact match to the URL stored on the terminal (or in webhookUrls).	Call GET /Terminals/{terminalId} to inspect webhookUrl.
HTTPS?	Only https:// endpoints are accepted.	URL must include https:// and a valid TLS cert.
Publicly reachable?	Bead cannot hit localhost or private IPs.	curl -I https://your-webhook from a public server.
Returns 2xx quickly?	Any non-2xx triggers retries; long timeouts count as failures.	Look at your server logs—should respond in < 1 s.
Firewall/WAF blocking Bead?	A firewall, WAF, or IP allowlist on your side may be rejecting Bead's requests before they reach your application.	See Firewall & IP Allowlisting for Webhooks for how to identify this and what to check.
Signature validation?	Handler isn't rejecting because of wrong signingSecret or timestamp skew.	Log the x-webhook-signature header and your verification result.
Event already sent?	Webhooks are only sent when statusCode changes.	Check payment timeline (GET /payments/tracking/{id}).

2 — Common scenarios & fixes

Symptom	Likely cause	Resolution
No hits in server logs at all	DNS typo or HTTPS certificate error	Re-enter URL, use Qualys SSL Labs to verify cert chain.
First attempt arrives, then retries keep going	Endpoint responds 500 or times out	Return 200 immediately, push heavy work to a queue.
Only terminal webhook receives events, extra webhookUrls do not	Missing webhookUrls array in the create-payment call	Confirm request body; array must be top-level, non-empty.
Handler logging "Invalid signature"	Wrong signingSecret or raw body altered before verification	Fetch latest secret via GET /Terminals/{id}. Verify raw body, not parsed JSON.
Webhooks work in sandbox but not in prod	Firewall, WAF, or region-restricted endpoint on your side	See Firewall & IP Allowlisting for Webhooks; confirm your rules aren't scoped to one environment's traffic pattern only.

3 — Debugging tips

1. Echo endpoint – Temporarily point the terminal webhook to https://webhook.site or https://requestbin.com to confirm Bead is sending events.

2. Verbose logging – Log headers, status code you return, and processing time.

3. Idempotency key – Use trackingId + statusCode to see if you've already processed the event.

4. Retry simulation – Respond with 500 in sandbox to observe back-off pattern (2 s, 4 s, 8 s, … up to 24 h).

5. Force a new status – Complete or cancel a sandbox payment to trigger another event.

4 — Still stuck?

• Double-check Step 1 above—small typos are the #1 culprit.

• If you suspect a firewall or WAF is blocking Bead's requests, see Firewall & IP Allowlisting for Webhooks.

• If everything looks correct, send us:

• Terminal ID

• Webhook URL

• Approximate timestamp of the event you expected

• Any logs you have