> 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. | Send a HEAD request to your webhook URL from a public server. | | **Accepts unauthenticated POSTs?** | The webhook route must accept a POST with no login session and answer with a 2xx from your handler. A route behind authentication, or one that redirects to a login page or another URL, never reaches your handler. | Send a test POST from outside your network, using the command below this table. Expect a 2xx. A `301` or `302` with a `location` header pointing at a login page means the route is protected. | | **Returns 2xx quickly?** | Any non-2xx triggers retries; long timeouts count as failures. | Look at your server logs—should respond in under 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 the payment status (`GET /Payments/{paymentId}/tracking`). | Test POST for the "Accepts unauthenticated POSTs?" check. Replace the URL with your own webhook URL: ```bash curl -i -X POST \ "https://your-host/your-webhook-path" \ --header "Content-Type: application/json" \ --data '{}' ``` Read the status line and the response headers. A `2xx` means your handler answered. A `301` or `302`, or an HTML page, means the request is not reaching your handler. #### 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. | | A POST to your URL returns `302` to a login page, or returns an HTML page instead of your handler's response | The webhook route is behind authentication, or a redirect or catch-all rule sends the request elsewhere | Allow anonymous requests on the webhook route only. Exempt it from login redirects and rewrite rules, then verify authenticity with the `x-webhook-signature` header inside your handler. Re-run the test POST above and confirm a 2xx from your handler. | | 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 `paymentId + statusCode` to see if you've already processed the event. Do not use the legacy `trackingId`. See [Payment Webhooks](/payments/payment-webhooks.md). 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. 6. **Test from outside your network** – Send a POST to your webhook URL and read the status line and headers. A redirect or an HTML page tells you the request is not reaching your handler. #### 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` 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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.