While Yousign webhooks are designed to be fast and reliable, issues can still occur—your server might be unavailable, slow, or return an error. To prevent data loss, Yousign implements a robust automatic retry policy.

❌ What Counts as a Failed Delivery?

A webhook delivery is considered failed if:

• Your server returns a status code other than 2xx or 3xx
• Your server doesn’t respond within the timeout window (see below)
• Your server redirects more than twice

When a failure is detected, and if your webhook subscription has auto_retry set to true, we’ll automatically retry the delivery up to 8 times using an exponential backoff strategy.

Even if you’ve explicitly set auto_retry: false, a single retry will still be attempted if the first failure was due to a timeout. This ensures minor response delays don’t silently cause data loss.

🔁 Retry Schedule and Delivery Behaviour

Here’s how retries are spaced:

Each webhook includes a header to indicate how many attempts have already occurred:

X-Yousign-Retry: 0 // First try

This makes it easy to monitor and differentiate retries from first deliveries.

• 0 means it’s the first attempt
• Higher numbers reflect retry attempts

Use this header to monitor delivery reliability or trigger fallback logic on your end.

If too many retries consistently fail for a specific endpoint, Yousign may temporarily suspend webhook deliveries to that endpoint until it becomes stable again. During this period, we’ll queue and retry deliveries later, once the endpoint is stable again.

⚡ Fail-Fast Timeout Strategy

To optimize delivery speed and avoid blocking resources, Yousign applies a fail-fast timeout policy:

⏳

If your server responds after the timeout, the webhook is still considered failed—even if it returns a valid 2xx or 3xx response.

🧠 Best Practices for Resilience

To make sure your system reliably handles webhooks and avoids duplicate processing or missed events, we recommend the following:

1. Respond quickly

Send a 2xx HTTP status as fast as possible—even if you haven’t processed the payload yet. Perform any heavy logic (like document downloads or DB writes) asynchronously using queues, background jobs, or workers.

2. Deduplicate using event_id

Webhook events include a globally unique event_id. Store this value and check for duplicates before processing to ensure idempotency—especially since retries can send the same event multiple times.

3. Track retry attempts

Use the X-Yousign-Retry header to monitor how many times a webhook has been retried.

✅ Summary

To ensure your integration is robust and reliable:

• Always respond quickly (ideally <1s) with a 2xx status
• Use the event_id to deduplicate repeated messages
• Monitor retries via the X-Yousign-Retry header
• Expect and handle retry delays (up to 2 days)
• Securely store and retry webhook data on your end if needed