docs: help users self-diagnose "Last delivery: Failed" webhooks

plugins/kapso/skills/integrate-whatsapp/SKILL.md

@@ -102,6 +102,12 @@ Test delivery:
 node scripts/test.js --webhook-id <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 <id>`.
+- Full checklist: `references/webhooks-overview.md` (Troubleshooting section).
+
 Always verify signatures. See:
 - `references/webhooks-overview.md`
 - `references/webhooks-reference.md`

plugins/kapso/skills/integrate-whatsapp/references/webhooks-overview.md

@@ -53,3 +53,28 @@ Batched payloads may include:
 
 - `X-Webhook-Batch: true`
 - `X-Batch-Size: <n>`
+
+## 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 <value>`, `--event <value>`, `--webhook-id <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 <id>
+   ```
+
+Then fix the endpoint (return `200 OK` within 10 seconds; verify the signature against the raw request bytes) and re-test.

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 <id>` (`integrate-whatsapp` skill).
+
+See `webhooks-overview.md` for the full troubleshooting checklist.