Notifications object

You can subscribe to notifications which will be sent to a specified endpoint. This endpoint will need to be publicly accessible.

"notifications": {
"destination": "https://mysite.com/events",
"subscriptions": [
"envelope_completion",
"envelope_ready",
"signer_completion",
"upload_errors",
"sign_offline_upload_errors",
"idv_resource_update",
"idv_session_completion",
"idv_check_completion",
"idv_task_completion",
"idv_session_limit_reached"
]
}

Parameter

Description

destination

Endpoint for notifications to be sent to. Only HTTPS endpoints with TLS 1.2 are supported.

envelope_completion

When all recipients have signed the document.

envelope_ready

The document is sealed.

envelope_created

The document is sealed.

  • this is an alias for envelope_ready

  • “envelope_ready” and “envelope_created” can both be subscribed to in the same envelope. If they are, both will be sent in the same trigger

signer_completion

The signer has signed.

upload_errors

When there is an error in the envelope creation process.

sign_offline___upload_errors

When there is an error in the process of uploading a document that was signed offline.

idv_resource_update

Specific to envelopes with an Identity verification check enabled. Update received whenever there are changes to resources in the IDV session. For example, a user uploading a new document.

idv_session_completion

Specific to envelopes with an Identity verification check enabled. Triggered when all tasks and all checks inside of a given session have been completed.

idv_check_completion

Specific to envelopes with an Identity verification check enabled. Sent when a check completes – for example a document authenticity check being performed.

idv_task_completion

Specific to envelopes with an Identity verification check enabled. Sent when a task is completed. If you require TEXT_EXTRACTION and the check has been fulfilled, Yoti will send this through as an update to your endpoint.

idv_session_limit_reached

Specific to envelopes with an Identity verification check enabled. When a recipient has reached their session limit. You can use the reset session limit endpoint to if you want the recipient to try again


Example Notifications

{
"envelope_id": "10aecb06-d50d-4f54-9e99-a85b63639837",
"status": "COMPLETE",
"platform": {
"type": "API"
},
"marked_for_deletion": false,
"details": {
"recipients": [
{
"id": "73a527f5-e217-4fa8-a47f-4c829892f722",
"name": "User3",
"email": "example3@gmail.com",
"type": "CC",
"tags": [],
"invitation_email_queued_at": "",
"sign_group_order": "",
"last_email_status": "SENT"
},
{
"id": "5b449856-c56d-464a-8fd4-32fe383a9745",
"sign_status": "SIGNED",
"name": "User2",
"email": "example2@gmail.com",
"auth_type": "no-auth",
"type": "WITNESS",
"tags": [
{
"envelope_id": "<UUID>",
"subscription_name": "upload_errors",
"status": "ERRORED",
"details": {
"errors": [
{
"file_name": "sample.pdf",
"code": "<ERROR MESSAGE>"
}
]
}
}
{
"envelope_id": "<UUID>",
"subscription_name": "envelope_ready",
"recipients": [
{
"Token": "<UUID>",
"Email": "example3@gmail.com"
}
],
"envelope_name": "Example-Envelope"
}
{
"envelope_id": "<UUID>",
"subscription_name": "signer_completion"
"status": "ACTIVE",
"details":
{
"recipients":
[
{
"id": "<UUID>",
"sign_status": "SIGNED",
"name": "User 1",
"email": "example@yoti.com",
"auth_type": "no-auth",
"role": "just a role",
"signed_at": "2021-01-01T00:00:00.000Z"
}
],
"completed_at": "2021-06-14T12:22:12.264Z",
"files": [
{
"id": "<UUID>",
"name": "sample.pdf"
}
]
}
}