> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/faqs-and-troubleshooting/webhooks-and-error-codes/why-am-i-not-receiving-webhook-events.md). # 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](/faqs-and-troubleshooting/webhooks-and-error-codes/firewall-and-ip-allowlisting-for-webhooks.md) 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](/faqs-and-troubleshooting/webhooks-and-error-codes/firewall-and-ip-allowlisting-for-webhooks.md); 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](/faqs-and-troubleshooting/webhooks-and-error-codes/firewall-and-ip-allowlisting-for-webhooks.md). * If everything looks correct, send us: * Terminal ID * Webhook URL * Approximate timestamp of the event you expected * Any logs you have --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.bead.xyz/faqs-and-troubleshooting/webhooks-and-error-codes/why-am-i-not-receiving-webhook-events.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.