◆Error Codes Wiki

Webhook Delivery Failure — Retry Logic and Endpoint Reliability Patterns

Warning5xx server error

Overview

Fix webhook delivery failures including timeout errors, endpoint unavailability, and implement reliable retry patterns for incoming webhooks.

Key Details

  • Webhooks are HTTP POST callbacks sent by external services when events occur
  • Most webhook providers expect a 2xx response within 5-30 seconds or consider the delivery failed
  • Failed deliveries are typically retried with exponential backoff (3-5 retry attempts over hours)
  • Webhook endpoints must be idempotent — the same event may be delivered multiple times
  • Common providers (Stripe, GitHub, Shopify) include signature headers for verifying webhook authenticity

Common Causes

  • Webhook endpoint returning 5xx errors due to application bugs or database issues
  • Endpoint processing time exceeding the provider's timeout (typically 5-30 seconds)
  • SSL certificate issues on the receiving endpoint causing connection failures
  • Firewall or security middleware blocking webhook POST requests from provider IP ranges

Steps

  1. 1Return 200 OK immediately upon receiving the webhook, then process the payload asynchronously
  2. 2Implement idempotency using the webhook event ID to prevent duplicate processing
  3. 3Verify webhook signatures to ensure authenticity before processing the payload
  4. 4Store raw webhook payloads in a queue (SQS, Redis) for reliable background processing
  5. 5Monitor webhook delivery success rates and set up alerts for consecutive failures

Tags

webhookretrydeliveryidempotentcallback

Related Items

http-api-rate-limit-429-too-many-requests

More in 5xx Server Error

http-500-internal-server-errorHTTP 500 Internal Server Error — What It Means & How to Fix It
Critical
http-501-not-implementedHTTP 501 Not Implemented — What It Means & How to Fix It
Critical
http-502-bad-gatewayHTTP 502 Bad Gateway — What It Means & How to Fix It
Critical
http-503-service-unavailableHTTP 503 Service Unavailable — What It Means & How to Fix It
Critical
http-504-gateway-timeoutHTTP 504 Gateway Timeout — What It Means & How to Fix It
Critical
http-505-http-version-not-supportedHTTP 505 HTTP Version Not Supported — What It Means & How to Fix It
Critical

Frequently Asked Questions

Webhook providers retry failed deliveries. If your endpoint was slow or returned an error, the provider sends the same event again. Implement idempotency by checking the event ID before processing.