Tighten the comparison and add what receivers need to handle in practice:
at-least-once and out-of-order delivery, signature verification (HMAC with
a shared secret), acknowledging quickly and processing in the background,
deduplicating by event ID, and combining webhooks with polling to catch
missed events.
Add the Standard Webhooks spec and GitHub's webhook best-practice and
signature-validation guides as resources.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
The topic said idempotency "sometimes" applies to POST but did not explain
how. Clarify which HTTP methods are idempotent by definition and describe
idempotency keys, the common way to make POST/PATCH safe to retry:
client-generated unique key, stored result replayed on repeats, reuse with
a different payload rejected, keys expire.
Add MDN, the IETF Idempotency-Key header draft and Stripe's reference
implementation as resources.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Rewrite the topic copy to reflect current practice: retry only transient
failures (timeouts, 429, 502-504), cap retries, use exponential backoff
with jitter, respect Retry-After, and retry only idempotent requests.
The old copy suggested retrying until a request succeeds, which can cause
retry storms.
Add three resources on backoff, jitter and Retry-After. No other topic in
the API Design, Backend or AI Engineer roadmaps covers these yet.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
