Failure and Retry Policy

In the context of Webhook delivery, will be considered as a failure a Webhook call to an endpoint that neither:

  • returns a 2XX nor 3XX HTTP response code,
  • returns a response within our timeout window.

In case the related Webhook Subscription has the auto-retry parameter set to true, these Webhooks will be retried after a short delay.

Delivery retries

Yousign will retry to call your endpoint up to 8 times using a back-off mechanism after 2min, 6min, 30min, 1h, 5h, 18h, 1 day and 2 days. This retry policy is available as long as the related Webhook Subscription is not deleted and the auto-retry parameter set to true.

Every Webhook sent will contain a custom header named X-Yousign-Retry-Count indicating the number of retries. For most requests, it will be 0 meaning it is the first attempt and that no retry was made on this webhook.

In irregular case of for a given time period and endpoint, too many retried Webhooks fail, we may be led to stop calling this endpoint until it is fixed. Until then, all Webhooks that should have been sent to this endpoint will automatically be saved to be retried later.


It might happen that we re-send a webhook that you already received, for instance in case of timeout before receiving your  2XX or 3XX HTTP response status. To prevent duplicates, you should save the event_id attribute and check its uniqueness.

Fail-fast policy

In order to ensure the best performances in delivery of our Webhooks, we introduced a fail-fast policy. This means that we have a very short timeout (1s) for first Webhook call, then a longer timeout (10s) in case of a retry .
Hence we encourage your application to send a 2xx/3xx response as soon as possible.
Please note those timeout values might be subject to change if we find better values


Webhooks failing on first try due to a too long response time will always be retried at least once, no matter the auto-retry parameter's value of the related Webhook Subscription. This second call, and all the following if applicable, will allow a longer response time before being considered in timeout.