Debugging webhook delivery failures

Every webhook endpoint has its own delivery log: the last 100 deliveries, what your server answered, and when the next attempt is due. It is the first place to look when your CRM, billing system, or notification rail stops receiving events.

Open the log

1. Open Webhooks in your reseller dashboard (/dashboard/reseller/webhooks).
2. Click Deliveries on the endpoint’s row.
3. Use the tiles at the top — All, Succeeded, Retrying, Exhausted — to filter by status.

Reading a row

Each row shows the event type, a status badge, how many attempts have been made, and your endpoint’s last HTTP status. No HTTP badge means we could not reach your server at all — DNS, TLS, or connection refused. Underneath: when the delivery was queued, when it was delivered or gave up, and when the next attempt is due.

Statuses: pending means queued or retrying; succeeded means your endpoint returned 2xx; exhausted means all 8 attempts are used up and we will not try again on our own.

Click a row to expand it. You will see the delivery id (the same value we send in the X-Vicifast-Delivery header), the last error, and the last response body we received — we store up to 1,000 characters, which usually contains your framework’s actual error message.

Common failure patterns

401 / 403 — signature mismatch

Your verification logic is rejecting the request. The most common cause: hashing a re-stringified copy of the body instead of the raw bytes. Frameworks like Express need app.use(express.raw()) on the webhook route — JSON middleware mutates the payload before you hash it. Fix the verifier, then retry an exhausted delivery (below) to confirm.

404 — endpoint moved

Endpoint URLs cannot be edited after creation. Add a new endpoint with the corrected URL (you will get a fresh signing secret), then delete the old one. Deleting removes the old endpoint’s delivery history, so retry anything worth saving first — retries always go to the URL configured on that endpoint.

5xx — your service was down

We back off exponentially: 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours, 24 hours, 48 hours, 72 hours — about a 7-day window. As long as your endpoint recovers within that window the event lands. If it does not, the delivery flips to exhausted; it stays in the log for audit but will not fire again unless you retry it manually.

Connection / TLS errors

Certificate expired, DNS pointing at the wrong host, a firewall blocking our egress. The expanded row’s Last error field will say ECONNREFUSED, certificate has expired, and so on. Fix the underlying infrastructure issue, then retry the failed deliveries.

Retrying an exhausted delivery

1. Fix whatever made the delivery fail first — a retry changes nothing otherwise.
2. If the endpoint is paused, resume it from the webhooks list; retry is refused while the endpoint is paused.
3. In the log, expand the exhausted row and click Retry.

Retry resets the attempt count to zero and flips the delivery back to pending with a fresh 8-attempt budget; it goes out on the next delivery tick. The delivery keeps its original id, so the X-Vicifast-Delivery header is unchanged — if your idempotency layer already processed it and short-circuits, that is expected.

Rotating the signing secret

Delete the endpoint and add a fresh one. The new endpoint gets a new secret, shown once at creation. Deleting removes the endpoint’s whole delivery history and drops any still-pending deliveries, so rotate during a quiet moment.

What we don’t retry

Nothing, based on status code: every non-2xx response — including 404 and 410 — is treated as a failure and retried on the normal backoff schedule. There is no "stop calling me" status code. If you have taken an endpoint down for good, pause or delete it in the dashboard instead. Deliveries still pending when the worker reaches a paused endpoint are marked exhausted with the error "endpoint disabled".

Good to know

• The log keeps the latest 100 deliveries per endpoint.
• Deliveries are sent by a worker that ticks once an hour (at :07 past the hour). A scheduled retry fires on the first tick at or after its backoff time, and a manual Retry goes out on the next tick — not instantly.
• The stored response body is capped at 1,000 characters; log verbosely on your own side if you need the full picture.