> 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.                  |
| **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 [**developers@bead.xyz**](mailto:developers@bead.xyz) and we’ll investigate.


---

# 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:

```
GET https://developers.bead.xyz/faqs-and-troubleshooting/webhooks-and-error-codes/why-am-i-not-receiving-webhook-events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.