Webhook subscription

To be able to receive Webhooks, you first need to create a Webhook Subscription with your triggering rules and target endpoint.

A Webhook Subscription is defined by the following attributes:

endpointThe secure URL called to send the Webhook.
descriptionA short description of this Webhook Subscription's purpose. It will be shown in Webhook's payload.
secret_keyThe secret key used to sign the Webhooks' payload and validate their authenticity, see Security
sandboxSpecify if Webhook should be triggered by events either in sandbox or production, see below.
enabledIs the Webhook Subscription active.
auto_retryDoes the Webhook should be retried later atfer a failure, see Retry policy.
subscribed_eventsList of Events you want to subscribed, see Events.
scopeList of Scopes in which the Webhooks should be triggered, see Scopes.


Webhook & Sandbox

  • If you are in API trial, you only have access to the Sandbox environment. You are limited in the Webhook Subscription creation: you can create Webhook Subscriptions only from the application, and not from the API.

  • Once you have access to production environment, if you want to continue carrying out tests including Webhook notifications, you can create a Webhook Subscription with the environment set to sandbox. You will receive the same Webhooks you would receive in Production, the only difference will be the parameter Sandbox which will be equal to true.

You can create Webhook Subscriptions in the Webhook section of your Developer Space

Or through our dedicated API endpoint.


Signature Request

Following events are related to the global lifecycle of the Signature Request.

signature_request.activatedA Signature Request has been activated (status went from draft to ongoing).
signature_request.doneA Signature Request has been completed, all Signers have signed.
signature_request.expiredA Signature Request has expired.
signature_request.reminder_executedA manual reminder has been sent.
signature_request.approvedA Signature Request has been approved by all the requested Approvers.
signature_request.declinedA specific Signer has declined to sign the Signature Request. The reason for declining is specified in the Webhook's payload.
signature_request.permanently_deletedA signature request has been permanently deleted.


Following events are related to the lifecycle of a specific Signer within the Signature Request.

signer.notifiedA specific Signer can now sign.
signer.link_openedA specific Signer opened the Signature Link for the first time.
signer.doneA specific Signer has completed its Signature Request.
signer.sender_contactedA specific Signer asked for a change in the Signature Request. This event is only available for the levels "Advanced eSignature" and "Qualified eSignature".
signer.identification_blockedA specific Signer failed the identity verification and cannot proceed further in the signature flow. This event is only available for the Advanced eSignature level.
signer.errorA specific Signer failed to sign due to an internal error during the signing process, in that case the Signature Request is automatically cancelled.
The document may be corrupted. If the error persists, please contact support.
signer.declinedA specific Signer has declined to sign the Signature Request. The reason for declining is specified in the Webhook's payload.
signer.identity_savedA specific Signer saved their digital identity. If that Signer is invited to sign again, they will be able to reuse this identity for faster identification. Due to strict comparison rules, using the digital identity is only enabled if Signer details did not change between Signature Requests. This event is only available for the "Qualified eSignature" level.


You can receive signer.done events even if the Signature Request is not completed in the case where some Signers have not signed yet.


If you want to know when all Signers have signed and that the Signature Request is completed, you can just listen to the signature_request.done event.


Following events are related to Contact management.

contact.createdA Contact has been created (excluding Contact created through CSV import).


Following events are related to Approvers management.

approver.notifiedAn approver gets the information that a Signature Request needs their approval.
approver.approvedAn approver approved the signature request.
approver.rejectedAn approver rejected the signature request.

Electronic Seal

Following events are related to Electronic Seal product.

electronic_seal.doneSeal processed successfully.
electronic_seal.errorSeal processing failed.

Events wildcard

If you want to subscribe to all events, you can directly use wildcard * as the only element of the list subscribed_events.


Events Payload

You can find a payload example for each of these Events type here.


The scope represents the context in which the resource has started its lifecycle. By defining a scope for your Webhook Subscription, it means that a Webhook will only be sent when the related resource match with one of these scopes.

Although several scopes exist, the two mains are:

  • app, when the resource has been created through Yousign application,
  • public_api, when it was through the public API.

Scopes wildcard

If you want to subscribe to all the scopes, you can directly use wildcard * as the only element of the list scopes.