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:
| 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 atfer a failure, see Retry policy. |
| subscribed_events | List of Events you want to subscribed, see Events. |
| scope | List 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 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
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.reminder_executed | A manual reminder has been sent. |
signature_request.approved | A Signature Request has been approved by all the requested Approvers. |
signature_request.declined | A specific Signer has declined to sign the Signature Request. The reason for declining is specified in the Webhook's payload. |
signature_request.permanently_deleted | A signature request has been permanently deleted. |
Signer
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 and Qualified eSignature levels. |
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
Following events are related to Contact management.
| Event | Description |
|---|---|
contact.created | A Contact has been created (excluding Contact created through CSV import). |
Approver
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
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, 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.
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, you can directly use wildcard * as the only element of the list scopes.
Updated 8 days ago