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.
IP allowlist?	Firewalls or WAFs aren’t blocking Bead’s IP range.	Temporarily disable rules or add Bead IPs (see portal).
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 or region-restricted endpoint	Allow Bead prod IPs; check CDN or geo-fencing rules.

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 everything looks correct, send us:

  • Terminal ID

  • Webhook URL

  • Approximate timestamp of the event you expected

  • Any logs you have

• Email [email protected] and we’ll investigate.