From f06a01406c9fca73a92d8d333b4377e4b012dcbe Mon Sep 17 00:00:00 2001 From: "posthog[bot]" <206114724+posthog[bot]@users.noreply.github.com> Date: Wed, 1 Jul 2026 20:34:02 +0000 Subject: [PATCH] docs: add "Last delivery: Failed" webhook troubleshooting and diagnostic cross-links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Users hitting "Last delivery: Failed" were re-editing event triggers and buffering settings, which cannot affect delivery success — delivery depends only on how the receiving endpoint responds. - Add a troubleshooting section to webhooks-overview.md and webhooks-reference.md naming the real causes (non-200, timeout, signature mismatch, wrong webhook scope) and stating that triggers/buffering do not affect delivery. - Cross-link the webhook editing docs (SKILL.md) to the webhook-deliveries.js diagnostic and the test.js test-delivery flow so users diagnose the endpoint instead of tweaking config. - Note in the Buffering reference that it does not affect delivery success. Generated-By: PostHog Code Task-Id: 430f00fb-8e08-4d83-8ad4-3552290c855b --- .../kapso/skills/integrate-whatsapp/SKILL.md | 6 +++++ .../references/webhooks-overview.md | 25 +++++++++++++++++++ .../references/webhooks-reference.md | 18 +++++++++++++ 3 files changed, 49 insertions(+) diff --git a/plugins/kapso/skills/integrate-whatsapp/SKILL.md b/plugins/kapso/skills/integrate-whatsapp/SKILL.md index d38dd09..f6f6a36 100644 --- a/plugins/kapso/skills/integrate-whatsapp/SKILL.md +++ b/plugins/kapso/skills/integrate-whatsapp/SKILL.md @@ -102,6 +102,12 @@ Test delivery: node scripts/test.js --webhook-id ``` +Troubleshoot "Last delivery: Failed": +- Delivery success depends only on the **receiving endpoint** (non-200, timeout, signature mismatch, wrong scope). Event triggers and buffering/debouncing settings do **not** affect it — editing them will not clear a failed delivery. +- Inspect real delivery attempts and errors: `node scripts/webhook-deliveries.js --errors-only true` (in the `observe-whatsapp` skill). +- Re-send a test delivery to the endpoint: `node scripts/test.js --webhook-id `. +- Full checklist: `references/webhooks-overview.md` (Troubleshooting section). + Always verify signatures. See: - `references/webhooks-overview.md` - `references/webhooks-reference.md` diff --git a/plugins/kapso/skills/integrate-whatsapp/references/webhooks-overview.md b/plugins/kapso/skills/integrate-whatsapp/references/webhooks-overview.md index 03e82b3..5b4b27a 100644 --- a/plugins/kapso/skills/integrate-whatsapp/references/webhooks-overview.md +++ b/plugins/kapso/skills/integrate-whatsapp/references/webhooks-overview.md @@ -53,3 +53,28 @@ Batched payloads may include: - `X-Webhook-Batch: true` - `X-Batch-Size: ` + +## Troubleshooting: "Last delivery: Failed" + +A "Failed" status is determined entirely by how your **receiving endpoint** responded — not by which events the webhook subscribes to or its buffering/debouncing settings. Changing event triggers or buffering does **not** affect delivery success, so re-editing those settings will never clear a failed delivery. + +Common causes: + +- **Non-200 response**: the endpoint returned a status other than `200 OK`. Kapso retries (see retry schedule above), then marks the delivery failed. +- **Timeout**: the endpoint did not respond within 10 seconds. +- **Signature mismatch**: the endpoint rejected the request while verifying `X-Webhook-Signature` (commonly from hashing parsed JSON instead of the raw request bytes — see [Signature verification](#signature-verification)). +- **Wrong webhook scope**: the event is not delivered on this webhook. `whatsapp.message.*` and `whatsapp.conversation.*` are delivered only on phone-number webhooks; lifecycle/workflow events only on project webhooks. See `webhooks-reference.md`. + +Diagnose the endpoint (don't edit triggers or buffering): + +1. Inspect the actual delivery attempts, response codes, and errors — `webhook-deliveries.js` in the `observe-whatsapp` skill: + ```bash + node scripts/webhook-deliveries.js --errors-only true + ``` + Also supports `--status `, `--event `, `--webhook-id `, and `--period <24h|7d|30d>`. +2. Re-send a controlled test delivery to the endpoint — `test.js` in the `integrate-whatsapp` skill: + ```bash + node scripts/test.js --webhook-id + ``` + +Then fix the endpoint (return `200 OK` within 10 seconds; verify the signature against the raw request bytes) and re-test. diff --git a/plugins/kapso/skills/integrate-whatsapp/references/webhooks-reference.md b/plugins/kapso/skills/integrate-whatsapp/references/webhooks-reference.md index 8514235..028651e 100644 --- a/plugins/kapso/skills/integrate-whatsapp/references/webhooks-reference.md +++ b/plugins/kapso/skills/integrate-whatsapp/references/webhooks-reference.md @@ -55,3 +55,21 @@ Use buffering to batch rapid inbound messages: - `buffer_enabled`: true - `buffer_window_seconds`: 1-60 - `max_buffer_size`: 1-100 + +Buffering only controls how inbound `message.received` events are batched before sending. It does **not** affect whether a delivery succeeds — a "Last delivery: Failed" status is never fixed by changing buffering or event triggers. See "Delivery troubleshooting" below. + +## Delivery troubleshooting ("Last delivery: Failed") + +A delivery is marked failed based on how your **receiving endpoint** responds, not on the webhook's event triggers or buffering settings. Real causes: + +- **Non-200 response** — endpoint returned something other than `200 OK`. +- **Timeout** — endpoint did not respond within 10 seconds. +- **Signature mismatch** — endpoint rejected the request while verifying `X-Webhook-Signature` (verify against raw bytes, not parsed JSON). +- **Wrong webhook scope** — the event isn't delivered on this webhook (see Scopes above). + +Diagnose instead of re-editing config: + +- List real delivery attempts and errors: `node scripts/webhook-deliveries.js --errors-only true` (`observe-whatsapp` skill; also `--status`, `--event`, `--webhook-id`, `--period`). +- Re-send a test delivery: `node scripts/test.js --webhook-id ` (`integrate-whatsapp` skill). + +See `webhooks-overview.md` for the full troubleshooting checklist.