Skip to content

feat(webhooks): classify delivery responses as success, retryable, or permanent - #929

Closed
Goodyslim wants to merge 1 commit into
Core-Foundry:mainfrom
Goodyslim:feat/643-webhook-response-classifier
Closed

Goodyslim wants to merge 1 commit into
Core-Foundry:mainfrom
Goodyslim:feat/643-webhook-response-classifier

Conversation

@Goodyslim

Copy link
Copy Markdown

Closes #643

What

Webhook delivery outcomes were classified implicitly and in two places that could drift. This introduces one documented rule set shared by both the delivery service and the retry helper.

Changes

  • listener/src/services/webhook-response-classifier.ts (new) - classifyWebhookResponse({ statusCode?, error }) returns exactly one of:
    • success - HTTP 2xx
    • retryable - network/timeout error, or HTTP 408/425/429, or any 5xx
    • permanent - any other 4xx, 1xx/3xx, or a missing status with no error
      The rules are documented in the module header, and RETRYABLE_STATUS_CODES / isRetryableClassification are exported.
  • webhook-delivery-service.ts - uses the classifier and now returns classification on WebhookDeliveryResult. Log behavior is unchanged for the existing categories (5xx -> warn, 4xx -> error, timeout -> warn, network -> error); transient non-5xx (408/425/429) now correctly warn instead of error.
  • webhook-retry-helper.ts - isRetryable delegates to the classifier, removing the duplicated status sets.

Acceptance criteria

  • Successful HTTP responses are classified correctly.
  • Temporary failures can be retried.
  • Permanent client failures are not retried indefinitely (bounded to 1 initial + 2 retries).
  • Classification rules are documented.
  • Tests cover representative HTTP status codes.

Validation

  • jest src/services/webhook-response-classifier.test.ts src/services/webhook-delivery-service.test.ts src/services/webhook-retry-helper.test.ts -> 3 suites, 85 tests pass.
  • The new files typecheck cleanly. Note: main has pre-existing, unrelated syntax errors in src/utils/request-id.ts that fail the repo-wide tsc.

… permanent

Add a single documented classifier (webhook-response-classifier.ts) that maps an HTTP response or thrown error to success (2xx), retryable (network/timeout, 408/425/429, any 5xx), or permanent (other 4xx, 1xx/3xx). The delivery service and the bounded retry helper both delegate to it, so they can no longer disagree: permanent client failures are never retried and transient failures are. WebhookDeliveryResult now carries the explicit classification.

Closes Core-Foundry#643
@Goodyslim

Copy link
Copy Markdown
Author

Superseded by #1030: main already contains the classifier and tests; the remaining acceptance gap was documentation, now covered by one conflict-free PR for #643.

@Goodyslim Goodyslim closed this Oct 23, 2026
@Goodyslim

Copy link
Copy Markdown
Author

Correction: superseded by #1100 (the conflict-free documentation PR for #643).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Classify Webhook Delivery Responses

1 participant