---
title: "Troubleshoot webhook notifications"
description: "Diagnose routing gaps, HMAC failures, stale requests, duplicates, delivery timeouts and exhausted retries using verified sender behavior."
slug: "/docs/v1/guides/webhook-troubleshooting"
section: "Webhooks and integrations"
order: 146
audience: "all"
level: "intermediate"
last_updated: "2026-10-18"
version: "v1"
related: ["/docs/v1/guides/test-webhooks-locally","/docs/v1/guides/webhook-delivery"]
draft: false
---
Find the failed boundary before retrying a notification or changing a [license](/docs/v1/start/glossary#license).

## What you will learn

- Separate routing, authentication, persistence and business-processing failures.
- Recognize documented gaps rather than relying on misleading retry assumptions.
- Collect minimal evidence for support without disclosing credentials.

## Prerequisites

- Access to your workspace [Webhooks](/docs/v1/start/glossary#webhook) page.
- Private receiver logs containing event IDs and safe status codes, not raw secrets.
- The [event catalog](/docs/v1/guides/webhook-events) and [delivery contract](/docs/v1/guides/webhook-delivery).

## Check the boundaries in order

1. Confirm the business operation actually emits the expected event.
2. Check [organization](/docs/v1/start/glossary#organization), environment, [product](/docs/v1/start/glossary#product), endpoint status and subscribed event.
3. Match the event ID in Delivery history to your receiver inbox.
4. Verify transport/HTTP status and attempt count.
5. Check authentication against the exact raw request bytes.
6. Check the durable inbox/work transaction.
7. Reconcile current API state before repeating a business action.

Expected result: you identify the first failed boundary. Do not repeat create or renew just because an alert email or HTTP acknowledgement is missing.

## Routing and missing notifications

| Symptom | Verified cause or boundary | Fix |
| --- | --- | --- |
| No history row for an ordinary event | Endpoint did not match active status, environment, product or subscription | Check setup before repeating the business operation |
| No notification after [developer](/docs/v1/start/glossary#developer) [device](/docs/v1/start/glossary#device) release | That developer Devices action does not emit license.deactivated | Read current device/license state and use an audit workflow |
| No notification for every validation | license.validated is not an event | Use API logs for diagnosis, not a nonexistent event subscription |
| Events are missing across a disabled period | Ordinary publications do not target disabled endpoints | Reconcile your own records; enabling is not backfill |
| Send test queues but does not send | Disabled endpoint, deferred processing or delivery failure | Enable, inspect status/count/next attempt and test again |
| No reminder after another renewal | Reminder marker uses license and day count, not expiration revision | Schedule billing reminders in your backend and reconcile expiry |
| No expiration notification immediately after API refusal | The persistent expired transition is performed by maintenance | Enforce the API/signed validity decision without waiting for notification |

## Signature and envelope failures

| Symptom | Verified cause or boundary | Fix |
| --- | --- | --- |
| HMAC mismatch | Secret or raw bytes differ | Capture raw bytes before middleware and use the correct endpoint secret |
| Signature fails after Rotate | New attempts immediately use the replacement secret | Coordinate receiver configuration and run Send test |
| Old event passes freshness | Its delivery attempt was freshly signed | Check attempt timestamp, not event.created_at |
| Future/stale signature refused | Receiver clock or request freshness is outside policy | Correct clock synchronization; regenerate only synthetic local requests |
| Header ID/name differs from body | Untrusted or malformed envelope metadata | Refuse or quarantine; do not route by the header alone |
| [Sandbox](/docs/v1/start/glossary#sandbox) notification reaches [Live](/docs/v1/start/glossary#live) handler | Receiver URL/configuration overlaps environments | Pin expected signed environment and separate endpoint secrets |
| Same signature appears in two requests | Possible replay inside tolerance | Verify and deduplicate the authenticated event ID durably |

## Transport and processing failures

| Symptom | Verified cause or boundary | Fix |
| --- | --- | --- |
| 301 or 302 in history | Sender does not follow redirects | Configure the final HTTPS URL |
| No HTTP status, timeout error | Connection or total request timeout | Check TLS/DNS and acknowledge after fast durable persistence |
| Receiver returns 429 | The sender still follows its fixed retry delays | Reduce work per request; do not depend on Retry-After being honored |
| HTTP 200 but no durable work | Handler acknowledged before commit or lost its in-memory queue | Use a durable transactional inbox before sending 2xx |
| Repeated emails or renewals | Authentication was mistaken for business deduplication | Use a separate durable order/invoice effect key |
| Same event ID, different authenticated body | Conflicting reuse of an ID | Quarantine and investigate; do not apply a second action |
| Older state overwrites newer state | Delivery order is not guaranteed | Reconcile current scoped API state before updating your view |
| Key email contains a mask | Webhook payloads never contain the complete [license key](/docs/v1/start/glossary#license-key) | Use your secured issuance outbox; do not reconstruct the key |

## Retry and history limitations

| Symptom | Verified cause or boundary | Fix |
| --- | --- | --- |
| Retry does nothing at attempt 6 | Count is not reset; exhausted delivery is still guarded | Reconcile affected resource and contact support for investigation |
| Delivered notification cannot replay | Sender skips Delivered rows | Test locally with a synthetic fixture; do not repeat a real business effect |
| Next attempt is later than the listed delay | Due work waits for maintenance processing | Inspect next attempt and receiver health; the delay is a minimum |
| An old Delivered row is absent | Latest-250 view or 30-day delivered cleanup | Use your own minimal durable event/business ledger |
| Response body is truncated | Only a capped excerpt is retained | Log a safe correlation ID, never credentials or complete keys |

## Prepare a support request

1. Record the environment, affected endpoint host and approximate UTC time.
2. Include the authenticated event ID and dashboard attempt count/status.
3. Describe the expected event and the operation that triggered it.
4. Include only safe HTTP/error codes and your own correlation ID.
5. Contact hi@kdpika.com without attaching keys, signatures, complete payloads or [customer](/docs/v1/start/glossary#customer) payment details.

Expected result: support can identify the delivery without obtaining a secret. Do not ask a buyer for card details or paste a [developer API key](/docs/v1/start/glossary#developer-api-key) into a ticket.

## Expected result

You can distinguish a missed notification from an uncertain licensing operation and avoid compounding a failure with a duplicate mutation.

## Common mistakes

- Repeatedly pressing Retry after the attempt budget is exhausted.
- Repeating renew to compensate for a missing webhook.
- Assuming Delivered proves the receiver's business task finished.
- Treating a stale status in an event as the current authoritative license state.

## Security notes

Keep signature rejection responses generic. Never turn off authentication to make a callback succeed. A correct support/reconciliation workflow does not require changing the licensing API contract or sharing private keys.

## Troubleshooting

If none of the symptom tables identifies the issue, reproduce it with the [local synthetic inbox](/docs/v1/guides/test-webhooks-locally). Compare raw-byte verification, durable receipt and business processing independently before escalating.

## Next steps

Run [local signature and replay tests](/docs/v1/guides/test-webhooks-locally), then retest only the eligible failed delivery after fixing its cause.

## Related

- [Endpoint setup and rotation](/docs/v1/guides/webhooks-overview)
- [Idempotency limitations](/docs/v1/api/idempotency)
- [API key leak response](/docs/v1/security/api-key-leak-response)