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