Webhook retry mechanism

Overview

When Loop sends a webhook to your endpoint, it expects a successful HTTP response. If the delivery fails (for example due to a network issue or a non-success HTTP status code), Loop will automatically retry the webhook before marking it as permanently failed.

Key points:

• Each webhook is delivered once initially.
• If the initial attempt fails, Loop retries up to 20 additional times.
• Retries are scheduled at a fixed interval of 1 hour.
• After all retry attempts are exhausted, the webhook is marked as completely failed and no further automatic retries occur.

In total, a webhook can be attempted up to 21 times (1 initial attempt + 20 retries), over a maximum retry window of about 20 hours after the first failure.

What counts as a failure?

A delivery attempt is treated as failed if any of the following occur:

• Your endpoint is unreachable (DNS failure, connection timeout, TLS error, etc.).
• Your server returns a non-success HTTP status code (for example, 4xx or 5xx).
• The response from your endpoint times out according to Loop’s internal timeout configuration.

Important: Only successful attempts stop the retry process early. Once Loop receives a success response, it will not retry that specific webhook again.

Idempotency and duplicate handling

Because the same webhook event can be delivered multiple times (up to 21 attempts), your webhook endpoint must be idempotent.

Best practices:

• Use a unique event ID (provided by Loop) to detect duplicate deliveries.
• Store processed event IDs in a durable store (for example, a database table or cache).
• If a request arrives with an already-processed event ID, return a success response and skip reprocessing.

This ensures that retries don’t cause duplicate side effects (such as creating the same order, charge, or record multiple times).

How to design a reliable webhook endpoint

To work smoothly with Loop’s retry mechanism:

1. Return a 2xx status code only after success

   • Wait until your business operation is safely persisted (e.g., DB transaction committed).
   • Then return an HTTP 2xx response.

2. Fail fast on invalid payloads

   • Validate payload signatures (if configured).
   • Validate required fields and schema.
   • For invalid requests, return an appropriate 4xx status code.

3. Avoid long-running operations in the request handler

   • If possible, enqueue work to a background job queue and immediately return success once enqueued.
   • This reduces timeouts and unnecessary retries.

4. Implement rate limiting and graceful degradation

   • If you are under heavy load, prefer returning a clear error (e.g., 503) and scaling your infrastructure rather than silently dropping events.

Monitoring and troubleshooting failed webhooks

When a webhook is marked as completely failed (after all 20 retries), you should:

• Inspect logs on your side for the time window corresponding to each failed attempt (status codes, error messages, timeouts).
• Check infrastructure health (APIs, databases, DNS, TLS certificates, firewall rules).
• Review endpoint logic for possible validation issues or unexpected exceptions.

Depending on how Loop is integrated in your environment, you may also have:

• An internal dashboard listing webhook deliveries and their statuses.
• The ability to manually replay failed events after you’ve fixed the underlying issue.

FAQ

How many times will Loop retry a failed webhook?

Loop retries each failed webhook up to 20 times after the initial failure. After that, the webhook is marked as completely failed and no further automatic retries occur.

How often are retries attempted?

Retries are attempted at a fixed interval of 1 hour between each attempt.

What happens if one of the retry attempts succeeds?

As soon as any attempt receives a success response from your endpoint, Loop considers the webhook delivered and stops all remaining retries.