Monitor recipient actions and status changes including signing, bounces, and replacements.
Recipient events track key actions and status changes for recipients within an envelope. This page describes each event type, when it fires, and the additional data included in the payload.
Fires when a recipient becomes ready to receive an invitation. The recipient status changes to pending.This event fires after all previous recipients in the routing order have completed, or immediately for the first recipient when the envelope starts.
Fires when SignatureAPI sends the invitation email to a recipient. The recipient status changes to sent.This event only fires for recipients with delivery_type set to email.
Fires when a recipient opens the ceremony URL. To reduce duplicate events, this fires at most once every 60 seconds for the same IP address and user agent combination. The recipient has not yet authenticated at this point.The data object includes the recipient’s ip address, user_agent, and a session_id. Use session_id to correlate multiple events from the same ceremony session.
Some security platforms access the ceremony URL to prefetch content or scan for threats. These requests can trigger recipient.accessed before the intended recipient opens the link. To confirm that the human recipient has accessed the ceremony, use the recipient.viewed event instead.
Fires after a recipient authenticates and the documents are displayed in the ceremony. This confirms the recipient passed all authentication steps and can view the documents.The data object includes a session_id. Use it to correlate multiple events from the same ceremony session.
Fires when a recipient finishes all required actions in the ceremony. The recipient status changes to completed.For signers, this means they have signed and finalized. For approvers and preparers, this means they have reviewed and submitted their inputs.The data object includes a session_id. Use it to correlate multiple events from the same ceremony session.
Fires when a recipient declines the envelope. When a recipient rejects, the entire envelope is voided.The data.reason property contains the recipient’s explanation if they provided one. It is an empty string if no reason was given. The data object also includes a session_id.
Example payload
JSON
Copy
Ask AI
{ "id": "evt_4d5e6f7g8h9i0j1k2l3m", "type": "recipient.rejected", "timestamp": "2025-12-31T23:59:59.999Z", "data": { "object_id": "re_00ZeZjRaXCgT30n1eBx53N", "object_type": "recipient", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." }, "recipient_type": "signer", "recipient_key": "client", "reason": "Not the terms we agreed to on June.", "session_id": "ses_2X6eHBCL84MDGrLQX0mHI72" }}
Fires when the invitation email is temporarily undeliverable. The recipient status changes to soft_bounced. Common causes include a full mailbox or a temporary server issue.The data.detail property contains the bounce reason from the remote email server. Use the Resend Request endpoint to try delivering the invitation again.
Fires when the invitation email is permanently undeliverable. The recipient status changes to hard_bounced. Common causes include an invalid or nonexistent email address.The data.detail property contains the bounce reason from the remote email server. You can view further details, such as SMTP responses, in the Dashboard.
After a hard bounce, you cannot resend to this recipient. Use the Replace Recipient endpoint to assign a new person with a valid email address.
Fires when an error prevents the invitation from being sent to a recipient. The recipient status changes to failed.The data.detail property contains a description of the failure, such as the recipient’s email being on a blocklist.
You may need to use the Replace Recipient endpoint to assign a different person.
Fires when a recipient is replaced through the Replace Recipient endpoint. The original recipient’s status changes to replaced.The data object includes new_recipient_id and new_recipient_name identifying the replacement recipient.
