> For the complete documentation index, see [llms.txt](https://help.cerby.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.cerby.com/tips-and-troubleshooting/troubleshooting/webhooks/troubleshooting-webhook-deliveries-failing.md).

# Troubleshooting: Webhook deliveries failing

This article describes how to resolve the issue of webhook event deliveries not being received or failing repeatedly.

This article describes how to resolve webhook event deliveries that are not being received or are failing repeatedly.

## Problem description

* **Behavior:** Cerby events are not arriving at your endpoint, or the webhook status shows **Disabled** unexpectedly.
* **Context:** This can occur at any time after a webhook is created or after changes are made to your endpoint configuration.

## Cause

Webhook deliveries fail when Cerby cannot complete an HTTPS POST request to your endpoint, or when your endpoint returns a response that Cerby treats as a failure.

The following are common triggers:

* The endpoint URL is incorrect, unreachable, or not publicly accessible from the internet.
* The endpoint does not use HTTPS, or its TLS certificate is invalid or expired.
* The endpoint returns a 4xx response other than 408 or 429, which causes Cerby to stop retrying immediately.
* The endpoint returns a redirect. Cerby does not follow redirects.
* The endpoint does not respond within 25 seconds.
* All six delivery attempts were exhausted within the 24-hour delivery window.
* Repeated failures opened the circuit breaker for the endpoint, which pauses delivery.
* The webhook is disabled.
* Signature verification is rejecting requests that are actually valid.

## Who this affects

* Workspace **Owners**, **Super Admins**, and **Admins** who manage webhook endpoints.
* Developers who build systems that consume Cerby webhook events.

## Solution

### Solution 1: Check the webhook status

Before investigating your endpoint, confirm that the webhook is enabled.

To check the webhook status, you must complete the following steps:

1. Log in to your [Cerby](https://app.cerby.com/) workspace.
2. Select **Settings** from the left navigation. The **Workspace Configuration** page is displayed.
3. Select the **Webhooks** left tab.
4. Locate the webhook in the list and check the status chip on its card:
   * If the status shows **Disabled**, the webhook is not delivering events. Select the actions menu and select **Enable webhook** to resume deliveries.
   * If the status shows **Enabled**, continue to one of the solutions below based on the type of failure.

**Expected result:** When the webhook is enabled, Cerby resumes delivery for new events. Past events that occurred while the webhook was disabled are not replayed.

### Solution 2: Confirm the endpoint is reachable

Use the built-in endpoint test to separate a Cerby-side problem from an endpoint-side one. The test works even while the webhook is disabled.

To test the endpoint, you must complete the following steps:

1. Log in to your [Cerby](https://app.cerby.com/) workspace.
2. Select **Settings** from the left navigation. The **Workspace Configuration** page is displayed.
3. Select the **Webhooks** left tab.
4. Click the name of the webhook you want to test. The webhook detail page is displayed.
5. Click the **Test endpoint** button. A panel opens showing the endpoint URL and a description of the verification challenge.
6. Click the **Send test event** button. The panel displays the HTTP status along with the request and response details.

Interpret the result as follows:

* **A 2xx status:** Your endpoint is reachable and accepting deliveries. If live events are still missing, check your event subscriptions and then continue to Solution 5.
* **Blocked or unreachable:** Cerby could not complete a request at all. Confirm the URL resolves publicly, uses HTTPS with a valid certificate, and is not blocked by a firewall or a web application firewall.
* **A 4xx or 5xx status:** Your endpoint answered but rejected the delivery. Continue to Solution 3 for 4xx and Solution 4 for 5xx.

**Expected result:** The test result tells you whether Cerby can reach your endpoint independently of live event traffic.

### Solution 3: Resolve a 4xx fail-fast failure

If your endpoint is returning a 4xx response code other than 408 or 429, Cerby has permanently stopped retrying that delivery. A 4xx response indicates a configuration problem with your endpoint that will not resolve on its own.

The following are common causes:

* **401 Unauthorized:** Your endpoint requires authentication that Cerby is not providing. Remove the authentication requirement or update your endpoint logic to accept Cerby's requests.
* **403 Forbidden:** Your endpoint or a network appliance in front of it is rejecting the request. Check your firewall, web application firewall, and any user-agent filtering rules.
* **404 Not Found:** The webhook URL no longer resolves to a valid endpoint. Update the webhook URL.
* **410 Gone:** The endpoint was intentionally removed. Update or delete the webhook.

To update the webhook URL, you must complete the following steps:

1. Log in to your [Cerby](https://app.cerby.com/) workspace.
2. Select **Settings** from the left navigation. The **Workspace Configuration** page is displayed.
3. Select the **Webhooks** left tab.
4. Select the actions menu for the webhook you want to update. The available actions are displayed.
5. Select **Edit webhook**. The webhook detail page is displayed in edit mode.
6. Update the **Endpoint URL** field with the correct HTTPS endpoint URL. Your change is held until you save it.
7. Click the **Save changes** button. A success message is displayed.

**Expected result:** Future events are delivered to the corrected URL. Past failed deliveries are not replayed. To identify missed events, use the Cerby API's account or automation endpoints to query the current state of the affected resources.

### Solution 4: Resolve delivery exhaustion or a paused endpoint

If your endpoint was unavailable for an extended period, two mechanisms can stop deliveries.

**Retry exhaustion.** Cerby makes up to six delivery attempts for each event, spread over a 24-hour window with exponential backoff. When the window closes, the event is permanently undeliverable and Cerby does not replay it.

**Circuit breaker.** Repeated failures against the same endpoint open a circuit breaker for that endpoint, which pauses delivery instead of continuing to send requests to a host that is not answering. Cerby re-tests the endpoint after a cooldown that lengthens with each failure, up to one hour. When a re-test succeeds, delivery resumes automatically without any action from you. Events whose 24-hour window expired while the breaker was open are not replayed.

To reduce the chance of either, do the following:

* Ensure your endpoint responds with a 2xx status within 25 seconds, and process events asynchronously rather than inline.
* Disable the webhook in advance of a planned maintenance window, and enable it again when your endpoint is available.

{% hint style="info" %}
**NOTE:** Events that fall outside the 24-hour delivery window cannot be retrieved by webhook. To audit missed events, use the Cerby API's account or automation endpoints to query the current state of the affected resources.
{% endhint %}

**Expected result:** After your endpoint is restored, Cerby resumes delivery for new events on its next successful attempt.

### Solution 5: Fix signature verification rejections

If your endpoint is receiving requests but rejecting them during signature verification, the following issues are most common.

**Issue: Timestamp skew rejection**

Your verification code is rejecting requests because the `X-Cerby-Signature-Timestamp` value is more than five minutes old. To resolve this issue, do the following:

* Ensure your server clock is synchronized with an NTP server. Clock drift causes valid requests to appear stale.
* Do not buffer or queue incoming requests before verifying them. Verify the signature immediately upon receipt.

**Issue: Incorrect signed bytes**

Your verification code is computing the wrong bytes to verify against the signature. To resolve this issue, do the following:

* Use `<timestamp_ms>.<raw_body_bytes>` as the signed message, where `<timestamp_ms>` is the millisecond-precision Unix timestamp from `X-Cerby-Signature-Timestamp`, followed by a literal period, followed by the raw request body bytes.
* Use the raw request body bytes as received. Do not parse, re-serialize, or modify the JSON before verifying.

**Issue: Base64url padding**

The signature value in `X-Cerby-Signature` is base64url-encoded without padding. If your base64 decoder requires padded input, re-pad the value before decoding. Append `=` characters until the string length is a multiple of four. Never hard-code `==` across all algorithms, because an Ed25519 signature needs `==` and an HMAC-SHA256 signature needs a single `=`.

**Issue: Dual-sign during key rotation**

When Cerby is rotating the signing key of your webhook, each request includes two `X-Cerby-Signature` headers. Accept the request if either signature validates. Some HTTP frameworks collapse repeated headers into a comma-separated string. Split the value and try each row independently before rejecting.

**Issue: Unrecognized signing key ID**

Your verification code does not recognize the `X-Cerby-Signature-Key-Id` on an incoming request, which is the normal signal that a rotation started. Re-fetch both public keys from `GET /v1/event-webhooks/{webhook_id}/keys` and key your local lookup by key ID. Do not reject on an unknown key ID before refreshing.

For reference verification implementations in Python and Node.js, refer to [Implement a webhook receiver](https://help.cerby.com/developer-tools/cerby-webhooks/implement-a-webhook-receiver).

**Expected result:** After correcting your verification code, requests from Cerby are accepted and processed normally.

### Solution 6: Rotate a compromised signing key

If you suspect your signing key has been exposed, rotate it immediately. Rotating invalidates the old key after a 24-hour dual-sign grace period. During this window, Cerby signs requests with both the old and new keys.

{% hint style="danger" %}
**IMPORTANT:** Update your stored key within 24 hours of rotation. When the grace period ends, the old key expires and only the new key is accepted.
{% endhint %}

For the full rotation procedure, refer to [Rotate a webhook signing key](https://help.cerby.com/setup-and-admin/workspace-settings/webhooks/rotate-a-webhook-signing-key).

**Expected result:** After you update your stored key, your verification code accepts requests signed with the new key.

## Get help

If the issue persists, contact:

* **Your workspace Admin** for workspace access or configuration issues.
* **Cerby Support** at <support@cerby.com>.

## Related articles

**Feature guides:**

* [Explore webhook notifications](https://help.cerby.com/setup-and-admin/workspace-settings/webhooks/explore-webhook-notifications)
* [Create a webhook](https://help.cerby.com/setup-and-admin/workspace-settings/webhooks/create-a-webhook)
* [Test a webhook endpoint](https://help.cerby.com/setup-and-admin/workspace-settings/webhooks/test-a-webhook-endpoint)

**Developer reference:**

* [Implement a webhook receiver](https://help.cerby.com/developer-tools/cerby-webhooks/implement-a-webhook-receiver)


---

# 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://help.cerby.com/tips-and-troubleshooting/troubleshooting/webhooks/troubleshooting-webhook-deliveries-failing.md?ask=<question>&goal=<user_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.