Skip to main content

Webhook events

A webhook event is a notification we send when something happens, such as a signature, an agreement update, or a participant action.


What webhook events are​

A webhook event is an automatic notification for something that happened. That includes a document being signed, an agreement being updated, or a participant completing their part. You can react in your own system when the event arrives.


Event names​

Event names use a [main] [sub] [event] structure. Each part narrows down what happened:

Main Categories​

The 'main' category represents the broad area of the system where the event occurs, such as agreement, participant, sign_event, or email_event. This helps you quickly identify the general part of the system the event is related to.

Subcategories​

Subcategories provide more specific context within the main category, further narrowing down the area of the system or process the event pertains to. For example, in agreement.lifecycle, lifecycle is the subcategory providing specific insights into the agreement's lifecycle phase.

Events​

Finally, the 'event' itself denotes the exact occurrence or action within the subcategory, such as created, updated, fulfilled, etc. This level gives you the precise detail of what has just happened.


Events Categorization and Details​

The sections below list the events in each category:

Agreement Events​

Agreement events are the most common. They fire when an agreement, or part of its process, changes.


Draft​

agreement.draft.created​

Triggered when an agreement is created.

agreement.draft.updated​

Triggered when an agreement is updated. Can only trigger for agreements in a draft or open status.


Lifecycle​

agreement.lifecycle.pending​

Triggered when an agreement enters the pending state.

agreement.lifecycle.fulfilled​

Occurs when an agreement is fully signed and completed, but not yet generated.

agreement.lifecycle.finalized​

Fired when an agreement is fully signed and generated. This is the final state of an agreement.

agreement.lifecycle.cancelled​

Triggered if an agreement is rejected by cancelling the signing process.

agreement.lifecycle.opened​

Occurs when an agreement is opened for editing.

agreement.lifecycle.expired​

Triggered when an agreement expires. This can happen if the agreement is not signed within the specified time frame.


Validation​

agreement.validation.started​

Triggered when validation of the final agreement begins.

agreement.validation.completed​

Fired when the validation of the agreement is successfully completed.

agreement.validation.failed​

Occurs when validation of the agreement fails.


Generation​

agreement.generation.restarted​

Triggered when the generation of the signed PDF is restarted.

agreement.generation.started​

Triggered when the generation of the signed PDF is started.

agreement.generation.completed​

Triggered when the signed PDF is successfully generated.

agreement.generation.failed​

Occurs if the agreement generation process fails.


Partial generation​

These events are sent only to webhooks whose subscription includes them. Generating a partially signed document does not notify webhooks that subscribe only to agreement.generation.*.

agreement.partial_generation.started​

Triggered when generation of a partially signed document has started.

agreement.partial_generation.failed​

Occurs if generation of a partially signed document fails. The revision is failed and has no file.

agreement.partial_generation.finalized​

Fired when a partially signed document has been generated. The revision is current and the file is ready.


Audit Trail Verification​

agreement.audit_trail_verification.started​

Indicates the start of audit trail verification.

agreement.audit_trail_verification.completed​

Fired when the audit trail verification is completed successfully.

agreement.audit_trail_verification.failed​

Occurs if the audit trail verification fails.


PDF Verification​

agreement.pdf_verification.started​

Triggered when the verification of the signed PDF begins.

agreement.pdf_verification.completed​

Fired upon successful verification of the signed PDF.

agreement.pdf_verification.failed​

Occurs if PDF verification fails.


Participant Events​

Participant events occur whenver there is a change to one of the participants in a signing process.


participant.draft.created​

Triggered when a participant is created.

participant.draft.updated​

Fired when a participant’s details are updated.

participant.lifecycle.forwarded​

Occurs when a participant is forwarded to a different email.

participant.identity_enforcement.passed​

Occurs when a signer passes the identity enforcement check.

participant.identity_enforcement.failed​

Triggered when a signer fails the identity enforcement check.

participant.lifecycle.fulfilled​

Occurs when a participant fulfills their role in the agreement process.


Observer Events​

Observer events occur whenver there is a change to one of the observers in a signing process.


observer.draft.created​

Triggered when an observer is created.

observer.draft.updated​

Fired when an observer's details are updated.


Sign Events​

Sign events are occur during the signing process. It could be a visit to the signing room or a completed signature, for example.


Signing Room​

sign_event.signing_room.entered​

Occurs when a signer or approver enters the signing room.

sign_event.signing_room.left​

Triggered when a signer or approver leaves the signing room.


Sign​

sign_event.sign.initiated_sign​

Fired when a signer or approver initiates the signing process.

sign_event.sign.cancelled_sign​

Occurs if the signing process is cancelled.

sign_event.sign.completed_sign​

Triggered when a signer or approver successfully completes the signing.

sign_event.sign.requested_otp​

Fired when a signer requests a One Time Password (OTP) for signing.

sign_event.sign.received_otp​

Occurs when a signer receives the OTP for signing.

sign_event.sign.failed_to_receive_otp​

Triggered if the OTP for signing could not be delivered.

sign_event.sign.confirmed_otp​

Occurs when a signer successfully confirms the OTP.

sign_event.sign.changed_email_for_otp​

Triggered when a signer changes their email for OTP signing.

sign_event.error.reset​

Triggered if an error occurs during signing and the signature data needs to be reset.


Approval​

sign_event.approval.approved​

Fired when an approver approves the document for signing.

sign_event.approval.disapproved​

Occurs when an approver disapproves the document for signing.


Email Events​

If communication is enabled for an agreement, this category of events will be triggered when emails are sent to participants. This is useful for tracking the delivery of emails and ensuring that participants receive the necessary information.


email_event.agreement_invitation.delivery_failed​

Triggered when the delivery of an agreement invitation email fails.

email_event.agreement_invitation.delivered​

Fired when an agreement invitation email is successfully delivered.

email_event.agreement_invitation.all_delivered​

Occurs when all agreement invitation emails are successfully delivered.

email_event.agreement_finalized.delivery_failed​

Triggered when the delivery of an email with the final signed PDF fails.

email_event.agreement_finalized.delivered​

Fired when an email with the final signed PDF is successfully delivered.

email_event.agreement_finalized.all_delivered​

Occurs when with the final signed PDF is successfully delivered by email to all participants.

email_event.agreement_cancelled.delivery_failed​

Triggered when the delivery of an agreement cancellation email fails.

email_event.agreement_cancelled.delivered​

Fired when an agreement cancellation email is successfully delivered.

email_event.agreement_cancelled.all_delivered​

Occurs when all agreement cancellation emails are successfully delivered.

email_event.agreement_paused.delivery_failed​

Triggered when an email notifying that the agreement has been paused fails.

email_event.agreement_paused.delivered​

Fired when an email notifying that the agreement has been paused is successfully delivered.

email_event.agreement_paused.all_delivered​

Occurs when all emails notifying that the agreement has been paused are successfully delivered.

email_event.agreement_observer_invitation.delivery_failed​

Triggered when the delivery of an observer invitation email fails.

email_event.agreement_observer_invitation.delivered​

Fired when an observer invitation email is successfully delivered.

email_event.agreement_observer_invitation.all_delivered​

Occurs when all observer invitation emails are successfully delivered.

email_event.agreement_reminder.delivery_failed​

Triggered when the delivery of an agreement reminder email fails.

email_event.agreement_reminder.delivered​

Fired when an agreement reminder email is successfully delivered.

email_event.agreement_reminder.all_delivered​

Occurs when all agreement reminder emails are successfully delivered.

email_event.agreement_forwarded.delivery_failed​

Triggered when the forwarding of an agreement invitation fails.

email_event.agreement_forwarded.delivered​

Fired when the forwarding of an agreement invitation is successfully delivered.