Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 17 additions & 23 deletions templates/backend/webhooks.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,43 +3,37 @@
[DEPENDS ON: templates/backend/http.md, templates/backend/messaging.md]
[DEPENDS ON: templates/security/security.md, templates/backend/observability.md]

Rules for receiving inbound webhooks (provider callbacks, integration
events) under bursty load. Compose this template on demand for a service
that receives webhooks — it is not part of any stack chain by default.

The generic resilience substrate — idempotency, retry/backoff, DLQ,
debounce/coalesce, backpressure, fairness — is inherited from
messaging.md; this template adds only the HTTP-ingestion-specific surface.
Rules for receiving provider callbacks under bursty load, on top of the
messaging rules for idempotency, retries, DLQs and backpressure.

## Intake

- Expose a distinct intake URL per provider or connection — never
multiplex unrelated providers onto one endpoint; per-integration URLs
isolate failures, scope signature handling, and sharpen observability
- Expose one intake URL per provider or connection; never multiplex
providers onto one endpoint
- Scope failures, signature handling and metrics to that URL

## Verify at the edge

- Verify the provider signature before doing any work — reject forged or
malformed payloads before parsing, persisting, or enqueueing
- Verify against the exact bytes received, not a re-serialised copy, and
treat the raw body as untrusted until the signature checks out
- Verify the provider signature before any work; reject a forged or
malformed payload before parsing, persisting or enqueueing it
- Verify the exact bytes received, never a re-serialised copy
- Treat the raw body as untrusted until its signature checks out

## Respond fast

- Return 2xx within the provider's timeout budget: acknowledge receipt,
then process asynchronously — never run heavy work inline on the
request path
- Return 2xx within the provider's timeout: acknowledge, then process
asynchronously, never inline on the request path
- Persist or enqueue the event before responding so an acknowledged
event is never lost

## Survive provider retries

- Account for retry amplification — a non-2xx response makes the provider
resend, so a slow or failing handler multiplies inbound load
- Return 2xx even when intentionally skipping an event (duplicate,
irrelevant); reserve 5xx strictly for failures where redelivery is wanted
- Deduplicate on the provider's event ID — at-least-once delivery means
the same event will arrive more than once
- Expect a non-2xx response to make the provider resend, so a slow or
failing handler multiplies inbound load
- Return 2xx for an event skipped on purpose (duplicate, irrelevant)
- Return 5xx only where redelivery is wanted
- Deduplicate on the provider's event ID; at-least-once delivery sends the
same event more than once

## Testing
[EXTEND: base-testing]
Expand Down
2 changes: 1 addition & 1 deletion tests/baselines/template-quality.txt
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ templates/backend/messaging.md 96.8
templates/backend/microservices.md 93.5
templates/backend/monitoring.md 98.5
templates/backend/observability.md 96.6
templates/backend/webhooks.md 86.9
templates/backend/webhooks.md 100.0
templates/core/agents.md 100.0
templates/core/config.md 99.3
templates/core/docs.md 99.1
Expand Down
Loading