Reference

Webhook events reference

Every delivery body is an envelope {"event_id", "event", "timestamp", "data"}. This page documents data for each event. See Webhooks for signing, retries and redelivery.

Envelope#

Field	Type	Description
`event_id`	UUID	Identical across retries and redeliveries; de-duplicate on it.
`event`	string	One of the event names below.
`timestamp`	RFC 3339	When the event happened, UTC.
`data`	object	Event-specific payload.

Shared objects#

Document#

Field	Type	Description
`id`	UUID	Document ID.
`title`	string	Document title.
`status`	string	`DRAFT`, `PENDING`, `COMPLETED`, `REJECTED`, `EXPIRED` or `CANCELLED`, at the time of the event.
`organization_id`	UUID	Your organization.

Recipient#

Field	Type	Description
`id`	UUID	Recipient ID (same as in `GET /documents/{id}`).
`email`	string	Recipient email.
`name`	string	Recipient name.
`role`	string	`SIGNER`, `APPROVER`, `VIEWER`, `CC` or `PREPARER`.
`status`	string	`NOT_SENT`, `SENT`, `VIEWED`, `SIGNED`, `REJECTED`, `EXPIRED`, `BOUNCED` or `DELEGATED`.

Document events#

document.created#

A draft was created through the API, the app, a template, bulk sending or as the copy made by cancel. data: Document.

{
  "event_id": "5e0f8a1b-2c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "event": "document.created",
  "timestamp": "2026-10-19T08:30:12.418204+00:00",
  "data": {
    "id": "3f1c2a9e-5b7d-4c11-9a3e-0d4b8e2f6a71",
    "title": "Office lease",
    "status": "DRAFT",
    "organization_id": "a7d5e0c2-1f43-4b9a-8c6e-2e9f0b3d4c58"
  }
}

document.sent#

The document was sent. data: Document plus recipients, every recipient in signing order.

{
  "event_id": "8c4b2a10-6d5e-4f3a-9b8c-7d6e5f4a3b21",
  "event": "document.sent",
  "timestamp": "2026-10-19T08:31:02.110931+00:00",
  "data": {
    "id": "3f1c2a9e-5b7d-4c11-9a3e-0d4b8e2f6a71",
    "title": "Office lease",
    "status": "PENDING",
    "organization_id": "a7d5e0c2-1f43-4b9a-8c6e-2e9f0b3d4c58",
    "recipients": [
      {"id": "c2b8f4d1-7e3a-4f60-b5c9-8a1d2e3f4b67", "email": "[email protected]", "name": "Anna Nowak", "role": "SIGNER", "status": "SENT"},
      {"id": "e4d3c2b1-a0f9-4e8d-8c7b-6a5f4e3d2c1b", "email": "[email protected]", "name": "Office Manager", "role": "CC", "status": "NOT_SENT"}
    ]
  }
}

document.viewed#

A recipient opened their signing link for the first time. data: Document plus recipient.

{
  "event_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "event": "document.viewed",
  "timestamp": "2026-10-19T08:45:20.004512+00:00",
  "data": {
    "id": "3f1c2a9e-5b7d-4c11-9a3e-0d4b8e2f6a71",
    "title": "Office lease",
    "status": "PENDING",
    "organization_id": "a7d5e0c2-1f43-4b9a-8c6e-2e9f0b3d4c58",
    "recipient": {"id": "c2b8f4d1-7e3a-4f60-b5c9-8a1d2e3f4b67", "email": "[email protected]", "name": "Anna Nowak", "role": "SIGNER", "status": "VIEWED"}
  }
}

document.signed#

A recipient signed. Fires once per signer, right after recipient.signed with the same data. data: Document plus recipient.

{
  "event_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "event": "document.signed",
  "timestamp": "2026-10-19T09:12:43.981220+00:00",
  "data": {
    "id": "3f1c2a9e-5b7d-4c11-9a3e-0d4b8e2f6a71",
    "title": "Office lease",
    "status": "PENDING",
    "organization_id": "a7d5e0c2-1f43-4b9a-8c6e-2e9f0b3d4c58",
    "recipient": {"id": "c2b8f4d1-7e3a-4f60-b5c9-8a1d2e3f4b67", "email": "[email protected]", "name": "Anna Nowak", "role": "SIGNER", "status": "SIGNED"}
  }
}

document.rejected#

A recipient declined. data: Document plus reason (string or null). Sent together with recipient.rejected, which also identifies the recipient.

{
  "event_id": "3c4d5e6f-7a8b-4c9d-8e0f-2a3b4c5d6e7f",
  "event": "document.rejected",
  "timestamp": "2026-10-19T09:02:11.551030+00:00",
  "data": {
    "id": "3f1c2a9e-5b7d-4c11-9a3e-0d4b8e2f6a71",
    "title": "Office lease",
    "status": "REJECTED",
    "organization_id": "a7d5e0c2-1f43-4b9a-8c6e-2e9f0b3d4c58",
    "reason": "Wrong rent amount"
  }
}

document.completed#

Everyone signed and the sealed PDF is ready: download it with GET /documents/{id}/signed.pdf. data: Document.

{
  "event_id": "4d5e6f7a-8b9c-4d0e-9f1a-3b4c5d6e7f80",
  "event": "document.completed",
  "timestamp": "2026-10-19T09:12:44.123456+00:00",
  "data": {
    "id": "3f1c2a9e-5b7d-4c11-9a3e-0d4b8e2f6a71",
    "title": "Office lease",
    "status": "COMPLETED",
    "organization_id": "a7d5e0c2-1f43-4b9a-8c6e-2e9f0b3d4c58"
  }
}

document.cancelled#

The sender cancelled (voided) a draft or pending document. data: Document plus reason, cancelled_at (RFC 3339) and copy_document_id (the new draft when cancelled with copy_as_draft, else null).

{
  "event_id": "5e6f7a8b-9c0d-4e1f-8a2b-4c5d6e7f8091",
  "event": "document.cancelled",
  "timestamp": "2026-10-19T09:20:00.731882+00:00",
  "data": {
    "id": "3f1c2a9e-5b7d-4c11-9a3e-0d4b8e2f6a71",
    "title": "Office lease",
    "status": "CANCELLED",
    "organization_id": "a7d5e0c2-1f43-4b9a-8c6e-2e9f0b3d4c58",
    "reason": "Superseded by v2",
    "cancelled_at": "2026-10-19T09:20:00.702114+00:00",
    "copy_document_id": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d"
  }
}

document.expired#

expires_at passed before everyone signed. data: Document.

{
  "event_id": "6f7a8b9c-0d1e-4f2a-9b3c-5d6e7f8091a2",
  "event": "document.expired",
  "timestamp": "2027-01-17T00:05:03.000412+00:00",
  "data": {
    "id": "3f1c2a9e-5b7d-4c11-9a3e-0d4b8e2f6a71",
    "title": "Office lease",
    "status": "EXPIRED",
    "organization_id": "a7d5e0c2-1f43-4b9a-8c6e-2e9f0b3d4c58"
  }
}

Recipient events#

recipient.signed#

A recipient finished their part. data: Document plus recipient. When the last signer finishes, document.completed follows.

{
  "event_id": "7a8b9c0d-1e2f-4a3b-8c4d-6e7f8091a2b3",
  "event": "recipient.signed",
  "timestamp": "2026-10-19T09:12:43.979002+00:00",
  "data": {
    "id": "3f1c2a9e-5b7d-4c11-9a3e-0d4b8e2f6a71",
    "title": "Office lease",
    "status": "PENDING",
    "organization_id": "a7d5e0c2-1f43-4b9a-8c6e-2e9f0b3d4c58",
    "recipient": {"id": "c2b8f4d1-7e3a-4f60-b5c9-8a1d2e3f4b67", "email": "[email protected]", "name": "Anna Nowak", "role": "SIGNER", "status": "SIGNED"}
  }
}

recipient.rejected#

A recipient declined. data: Document plus recipient and reason.

{
  "event_id": "8b9c0d1e-2f3a-4b4c-9d5e-7f8091a2b3c4",
  "event": "recipient.rejected",
  "timestamp": "2026-10-19T09:02:11.548771+00:00",
  "data": {
    "id": "3f1c2a9e-5b7d-4c11-9a3e-0d4b8e2f6a71",
    "title": "Office lease",
    "status": "REJECTED",
    "organization_id": "a7d5e0c2-1f43-4b9a-8c6e-2e9f0b3d4c58",
    "recipient": {"id": "c2b8f4d1-7e3a-4f60-b5c9-8a1d2e3f4b67", "email": "[email protected]", "name": "Anna Nowak", "role": "SIGNER", "status": "REJECTED"},
    "reason": "Wrong rent amount"
  }
}

recipient.bounced#

The invitation email bounced or was reported as spam; the recipient's status becomes BOUNCED. Correct the address with PATCH /documents/{id}/recipients/{recipient_id} and resend. data differs from the other events:

Field	Type	Description
`document_id`	UUID	The document the invitation belonged to.
`recipient`	object	`id`, `email`, `status` (`BOUNCED`).
`reason`	string	Email provider event type: `email.bounced` or `email.complained`.

{
  "event_id": "9c0d1e2f-3a4b-4c5d-8e6f-8091a2b3c4d5",
  "event": "recipient.bounced",
  "timestamp": "2026-10-19T08:31:40.300120+00:00",
  "data": {
    "document_id": "3f1c2a9e-5b7d-4c11-9a3e-0d4b8e2f6a71",
    "recipient": {"id": "c2b8f4d1-7e3a-4f60-b5c9-8a1d2e3f4b67", "email": "[email protected]", "status": "BOUNCED"},
    "reason": "email.bounced"
  }
}

Bounces are detected for invitations sent through the platform's managed email delivery.

recipient.identity_verification_updated#

A recipient's identity check changed status. Fires once per transition: into IN_REVIEW and into a final status. It carries the status only; names, birth dates and PESEL never leave sign.yt.

Field	Type	Description
`document_id`	UUID	The document.
`recipient_id`	UUID	The recipient being verified.
`verification_id`	UUID	The attempt; a retry is a new attempt with a new ID.
`provider`	string	`didit`, `authologic` or `login_gov_pl`.
`status`	string	`IN_REVIEW`, `VERIFIED`, `MISMATCH` or `FAILED`.

{
  "event_id": "0d1e2f3a-4b5c-4d6e-9f70-91a2b3c4d5e6",
  "event": "recipient.identity_verification_updated",
  "timestamp": "2026-10-19T09:20:05.112233+00:00",
  "data": {
    "document_id": "3f1c2a9e-5b7d-4c11-9a3e-0d4b8e2f6a71",
    "recipient_id": "c2b8f4d1-7e3a-4f60-b5c9-8a1d2e3f4b67",
    "verification_id": "9b2e4c6a-1d3f-4a5b-8c7d-6e5f4a3b2c1d",
    "provider": "didit",
    "status": "VERIFIED"
  }
}

Flow events#

flow.step#

A flow notify step configured with channel: "webhook" ran. subject and message are the step's templates rendered with the run variables.

Field	Type	Description
`run_id`	UUID	Flow run.
`flow_id`	UUID or null	Flow definition.
`step_key`	string	Key of the notify step.
`subject`	string	Rendered subject.
`message`	string	Rendered message.
`variables`	object	Run variables at this step.

{
  "event_id": "0d1e2f3a-4b5c-4d6e-9f7a-91a2b3c4d5e6",
  "event": "flow.step",
  "timestamp": "2026-10-19T10:00:00.120001+00:00",
  "data": {
    "run_id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
    "flow_id": "f0e1d2c3-b4a5-4968-8776-655443322110",
    "step_key": "notify_crm",
    "subject": "Lease signed: Biuro Hello",
    "message": "Anna Nowak signed the lease.",
    "variables": {"client_name": "Anna Nowak", "client_email": "[email protected]"}
  }
}