Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(runbook): read delivery failures with an ADMIN key

Yudhi Armyndharis758e34bf720b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5a9c1a055..ad35e4635 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -68,6 +68,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- The migration guide checks that both queues are drained with a header-authenticated Bull Board call, and confirms `s3Available` before a storage migration.
- `SECURITY.md` says the bundled Docker Compose files are affected by a legacy `ENABLE_SWAGGER=true` in `.env`, and lists plugin activation and the session proxy route among the routes fenced from session-scoped keys.
- Java SDK: clear a webhook's filters with `new WebhookFilters(List.of())`; `filters(null)` leaves them unchanged.
+- The webhook runbook reads delivery failures with an ADMIN key and says a URL the SSRF guard blocks only at delivery time is recorded there.
### Upgrade notes (behavior changes)
diff --git a/docs/11-operational-runbooks.md b/docs/11-operational-runbooks.md
index 1498ccbf3..1015b0ba5 100644
--- a/docs/11-operational-runbooks.md
+++ b/docs/11-operational-runbooks.md
@@ -241,7 +241,7 @@ as a delivery failure rather than retaining payloads without limit.
**Prerequisites:**
-- API Key
+- API key, and an ADMIN key for step 2
- Access to webhook endpoint
**Steps:**
@@ -255,9 +255,13 @@ curl -H "X-API-Key: $API_KEY" \
# most-recent-first: those that exhausted every retry, plus those never attempted at all
# (recorded with `attempts: 0` — payload over the cap or an unserializable payload
# (preflight), inline waiter-queue overflow, or rejection by the shutdown drain).
-# A URL blocked by the SSRF guard never reaches delivery: it is rejected with a 400 when the
-# webhook is registered, so it appears in no delivery-failure row.
-curl -H "X-API-Key: $API_KEY" \
+# An overflow or shutdown row is replayed by the outbox sweep and removed once it delivers.
+# The SSRF guard refuses a blocked URL with a 400 when the webhook is registered. A URL that
+# passed then and is blocked at delivery (its host now resolves to a private address, or the
+# guard was switched on later) is recorded as "Destination address is not allowed". With the
+# guard on, the same text also stands for a host name that failed to resolve and for a
+# redirect, which deliveries never follow. The server log for that delivery names the cause.
+curl -H "X-API-Key: $ADMIN_API_KEY" \
"http://localhost:2785/api/webhooks/delivery-failures?sessionId={sessionId}&limit=20"
# Attempts still in flight (not yet exhausted) only appear in the server logs:
@@ -319,7 +323,7 @@ curl -X POST -H "X-API-Key: $API_KEY" \
# Expected: {"success": true, "statusCode": 200}
# No new permanent delivery failures for this session
-curl -H "X-API-Key: $API_KEY" \
+curl -H "X-API-Key: $ADMIN_API_KEY" \
"http://localhost:2785/api/webhooks/delivery-failures?sessionId={sessionId}&limit=5"
```