From 0b0bd5afb238935193f0973f42d8507d1b87f793 Mon Sep 17 00:00:00 2001
From: Goodyslim <332204418+Goodyslim@users.noreply.github.com>
Date: Fri, 23 Oct 2026 16:16:58 +0100
Subject: [PATCH] docs(webhooks): document response classification rules

---
 README.md                                     |  1 +
 .../docs/webhook-response-classification.md   | 29 +++++++++++++++++++
 2 files changed, 30 insertions(+)
 create mode 100644 listener/docs/webhook-response-classification.md

diff --git a/README.md b/README.md
index 7bbec810..d9449fb9 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,7 @@ The project enables developers to build reactive decentralized applications with
 
 CI quality checks: [dashboard accessibility](docs/accessibility-automation.md),
 [listener Node.js support](listener/docs/node-compatibility.md),
+[webhook response classification](listener/docs/webhook-response-classification.md),
 [critical event mutation testing](listener/docs/mutation-testing.md), and
 [contract build reproducibility](docs/CONTRACT_BUILD_REPRODUCIBILITY.md).
 
diff --git a/listener/docs/webhook-response-classification.md b/listener/docs/webhook-response-classification.md
new file mode 100644
index 00000000..7567c008
--- /dev/null
+++ b/listener/docs/webhook-response-classification.md
@@ -0,0 +1,29 @@
+# Webhook response classification
+
+Webhook delivery outcomes are classified by
+`listener/src/services/webhook-retry-helper.ts` so retries use one rule set.
+The classification is exercised by
+`listener/src/services/webhook-retry-helper.test.ts`.
+
+| Outcome | HTTP response / error | Retried? |
+| ------- | --------------------- | -------- |
+| Success | Any `2xx` | No |
+| Retryable | `408`, `425`, `429`, any `5xx`, request timeout, network error | Yes, bounded |
+| Permanent | `400`, `401`, `403`, `404`, `410`, `422`, other `4xx`, `1xx`, `3xx` | No |
+
+## Rules
+
+1. A response with a `2xx` status is a success.
+2. `408`, `425`, `429`, and every `5xx` status are retryable.
+3. Timeouts and network-level failures are retryable.
+4. Explicit permanent client errors (`400`, `401`, `403`, `404`, `410`, `422`)
+   and any other non-retryable status are permanent.
+5. Retries are bounded to the initial attempt plus two retries (`MAX_RETRY_ATTEMPTS`)
+   with a fixed delay (`RETRY_DELAY_MS`), so a permanent failure cannot loop
+   indefinitely.
+6. A response that is neither successful nor explicitly retryable defaults to
+   permanent. An unknown classification therefore under-retries rather than
+   retrying forever.
+
+The delivery path and the retry helper both call `classifyWebhookFailure`, so
+changing a status code here changes both consistently.