Webhook subscriptions
On this page, you will learn how to create webhook subscriptions by setting triggering rules and defining key attributes like endpoint URL, secret key, and subscribed events. This guide also covers event types, environments, and how to manage subscriptions for different workspaces.
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:
| Attribute | Description |
|---|---|
| endpoint | The secure URL called to send the Webhook. |
| description | A short description of this Webhook Subscription's purpose. It will be shown in Webhook's payload. |
| secret_key | The secret key used to sign the Webhooks' payload and validate their authenticity, see Security |
| sandbox | Specify if Webhook should be triggered by events either in sandbox or production, see below. |
| enabled | Is the Webhook Subscription active. |
| auto_retry | Does the Webhook should be retried later after a failure, see Retry policy. |
| subscribed_events | List of Events you want to subscribed to, see Events. |
| scope | List of Scopes in which the Webhooks should be triggered, see Scopes. |
| workspace | Webhook will only be triggered for events happening on resources belonging to this list of workspaces, see Workspaces. |
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 parameterSandboxwhich will be equal totrue.
You can create Webhook Subscriptions in the Webhook section of your Developer Space
Or through our dedicated API endpoint.
Events
Signature Request
The following events are related to the global lifecycle of the Signature Request.
| Event | Description |
|---|---|
signature_request.activated | A Signature Request has been activated (status went from draft to ongoing). |
signature_request.done | A Signature Request has been completed, all Signers have signed. |
signature_request.expired | A Signature Request has expired. |
signature_request.reactivated | An expired Signature Request is reactivated. |
signature_request.reminder_executed | A manual reminder has been sent. |
signature_request.approved | All the requested Approvers have approved a Signature Request. |
signature_request.declined | A specific Signer has declined to sign the Signature Request. The reason for the decline is specified in Webhook's payload. |
signature_request.canceled | A Signature Request has been cancelled. |
signature_request.deleted | A signature request has been deleted. |
signature_request.permanently_deleted | A signature request has been permanently deleted. |
Signer
The following events are related to the lifecycle of a specific Signer within the Signature Request.
| Event | Description |
|---|---|
signer.notified | A specific Signer can now sign. |
signer.link_opened | A specific Signer opened the Signature Link for the first time. |
signer.done | A specific Signer has completed its Signature Request. |
signer.sender_contacted | A 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_blocked | A 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.identification_succeeded | A specific Signer succeeded the identity verification. This event is available for the Qualified eSignature level and for the Advanced eSignature level. |
signer.identification_failed | A specific Signer failed the identity verification. This event also contains the reason for the failure and is only available for the Qualified eSignature level. |
signer.error | A 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.declined | A specific Signer has declined to sign the Signature Request. The reason for declining is specified in the Webhook's payload. |
signer.identity_saved | A 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.doneevents 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.doneevent.
Contact
The following events are related to Contact management.
| Event | Description |
|---|---|
contact.created | A Contact has been created (excluding Contact created through CSV import). |
Approver
The following events are related to Approvers management.
| Event | Description |
|---|---|
approver.notified | An approver gets the information that a Signature Request needs their approval. |
approver.approved | An approver approved the signature request. |
approver.rejected | An approver rejected the signature request. |
Electronic Seal
The following events are related to Electronic Seal product.
| Event | Description |
|---|---|
electronic_seal.done | Seal processed successfully. |
electronic_seal.error | Seal processing failed. |
Events wildcard
If you want to subscribe to all events (existing and future), you can directly use the 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.
Scopes
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 (existing and future), you can directly use the wildcard * as the only element of the list scopes.
Workspaces
Workspaces help you to ensure document confidentiality between your users and/or reflect your company's organization (departments, subsidiaries, agencies, etc.) and it is possible to have webhooks only triggered for events happening on specific workspaces.
To do this, you just have to list in your webhook creation or update payload the workspaces you want to listen to.
Workspaces wildcard
If you want to subscribe to all Workspaces (existing and future), you can directly use the wildcard * as the only element of the list workspace.
Updated about 2 months ago