Documenso
Webhooks

Webhook Events

Reference for all webhook event types and payloads.

Event Payload Structure

All webhook events share a common structure:

{
  "event": "DOCUMENT_COMPLETED",
  "payload": {
    // Document or template data with recipients
  },
  "createdAt": "2024-04-22T11:52:18.277Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

Top-Level Fields

FieldTypeDescription
eventstringEvent type identifier (e.g., DOCUMENT_CREATED)
payloadobjectDocument object with metadata and recipients
createdAtdatetimeWhen the webhook event was created
webhookEndpointstringThe URL receiving this webhook

Payload Fields

FieldTypeDescription
idnumberDocument or template ID
externalIdstring?External identifier for integration
userIdnumberOwner's user ID
authOptionsobject?Document-level authentication options
formValuesobject?PDF form values associated with the document
titlestringDocument or template title
statusstringCurrent status: DRAFT, PENDING, COMPLETED
visibilitystringDocument visibility setting
createdAtdatetimeDocument creation timestamp
updatedAtdatetimeLast modification timestamp
completedAtdatetime?Completion timestamp (when all recipients have signed)
deletedAtdatetime?Deletion timestamp
teamIdnumber?Team ID if document belongs to a team
templateIdnumber?Template ID if created from a template
sourcestringSource: DOCUMENT or TEMPLATE
documentMetaobjectDocument metadata (subject, message, signing options)
recipientsarrayList of recipient objects
RecipientarrayList of recipient objects (legacy, same as recipients)

Document Metadata Fields

FieldTypeDescription
idstringMetadata record identifier
subjectstring?Email subject line
messagestring?Email message body
timezonestringTimezone for date display
passwordstring?Document access password (if set)
dateFormatstringDate format string
redirectUrlstring?URL to redirect after signing
signingOrderstringPARALLEL or SEQUENTIAL
allowDictateNextSignerbooleanWhether signers can choose the next signer
typedSignatureEnabledbooleanWhether typed signatures are allowed
uploadSignatureEnabledbooleanWhether uploaded signatures are allowed
drawSignatureEnabledbooleanWhether drawn signatures are allowed
languagestringDocument language code
distributionMethodstringHow document is distributed
emailSettingsobject?Custom email settings for this document

Recipient Fields

FieldTypeDescription
idnumberRecipient ID
documentIdnumber?Parent document ID
templateIdnumber?Template ID if created from a template
emailstringRecipient email address
namestringRecipient name
tokenstringUnique signing token
documentDeletedAtdatetime?When the recipient hid the document
expiresAtdatetime?When the recipient's signing link expires
expirationNotifiedAtdatetime?When the expiration notification was sent
signedAtdatetime?When recipient signed
authOptionsobject?Per-recipient authentication options
rolestringRole: SIGNER, VIEWER, APPROVER, ASSISTANT, CC
signingOrdernumber?Position in signing sequence
readStatusstringNOT_OPENED or OPENED
signingStatusstringNOT_SIGNED, SIGNED, or REJECTED
sendStatusstringNOT_SENT or SENT
rejectionReasonstring?Reason if recipient rejected

Document Lifecycle Events

These events track the document through its lifecycle.

document.created

Triggered when a new document is created.

Event name: DOCUMENT_CREATED

{
  "event": "DOCUMENT_CREATED",
  "payload": {
    "id": 10,
    "externalId": null,
    "userId": 1,
    "authOptions": null,
    "formValues": null,
    "visibility": "EVERYONE",
    "title": "contract.pdf",
    "status": "DRAFT",
    "createdAt": "2024-04-22T11:44:43.341Z",
    "updatedAt": "2024-04-22T11:44:43.341Z",
    "completedAt": null,
    "deletedAt": null,
    "teamId": null,
    "templateId": null,
    "source": "DOCUMENT",
    "documentMeta": {
      "id": "doc_meta_123",
      "subject": "Please sign this document",
      "message": "Hello, please review and sign this document.",
      "timezone": "UTC",
      "password": null,
      "dateFormat": "MM/DD/YYYY",
      "redirectUrl": null,
      "signingOrder": "PARALLEL",
      "allowDictateNextSigner": false,
      "typedSignatureEnabled": true,
      "uploadSignatureEnabled": true,
      "drawSignatureEnabled": true,
      "language": "en",
      "distributionMethod": "EMAIL",
      "emailSettings": null
    },
    "recipients": [
      {
        "id": 52,
        "documentId": 10,
        "templateId": null,
        "email": "signer@example.com",
        "name": "John Doe",
        "token": "vbT8hi3jKQmrFP_LN1WcS",
        "documentDeletedAt": null,
        "expiresAt": null,
        "expirationNotifiedAt": null,
        "signedAt": null,
        "authOptions": null,
        "signingOrder": 1,
        "rejectionReason": null,
        "role": "SIGNER",
        "readStatus": "NOT_OPENED",
        "signingStatus": "NOT_SIGNED",
        "sendStatus": "NOT_SENT"
      }
    ],
    "Recipient": [
      {
        "id": 52,
        "documentId": 10,
        "templateId": null,
        "email": "signer@example.com",
        "name": "John Doe",
        "token": "vbT8hi3jKQmrFP_LN1WcS",
        "documentDeletedAt": null,
        "expiresAt": null,
        "expirationNotifiedAt": null,
        "signedAt": null,
        "authOptions": null,
        "signingOrder": 1,
        "rejectionReason": null,
        "role": "SIGNER",
        "readStatus": "NOT_OPENED",
        "signingStatus": "NOT_SIGNED",
        "sendStatus": "NOT_SENT"
      }
    ]
  },
  "createdAt": "2024-04-22T11:44:44.779Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

document.sent

Triggered when a document is sent to recipients for signing.

Event name: DOCUMENT_SENT

The document status changes to PENDING and recipients have sendStatus: "SENT".

{
  "event": "DOCUMENT_SENT",
  "payload": {
    "id": 10,
    "externalId": null,
    "userId": 1,
    "authOptions": null,
    "formValues": null,
    "visibility": "EVERYONE",
    "title": "contract.pdf",
    "status": "PENDING",
    "createdAt": "2024-04-22T11:44:43.341Z",
    "updatedAt": "2024-04-22T11:48:07.569Z",
    "completedAt": null,
    "deletedAt": null,
    "teamId": null,
    "templateId": null,
    "source": "DOCUMENT",
    "documentMeta": {
      "id": "doc_meta_123",
      "subject": "Please sign this document",
      "message": "Hello, please review and sign this document.",
      "timezone": "UTC",
      "password": null,
      "dateFormat": "MM/DD/YYYY",
      "redirectUrl": null,
      "signingOrder": "PARALLEL",
      "allowDictateNextSigner": false,
      "typedSignatureEnabled": true,
      "uploadSignatureEnabled": true,
      "drawSignatureEnabled": true,
      "language": "en",
      "distributionMethod": "EMAIL",
      "emailSettings": null
    },
    "recipients": [
      {
        "id": 52,
        "documentId": 10,
        "templateId": null,
        "email": "signer@example.com",
        "name": "John Doe",
        "token": "vbT8hi3jKQmrFP_LN1WcS",
        "documentDeletedAt": null,
        "expiresAt": null,
        "expirationNotifiedAt": null,
        "signedAt": null,
        "authOptions": null,
        "signingOrder": 1,
        "rejectionReason": null,
        "role": "SIGNER",
        "readStatus": "NOT_OPENED",
        "signingStatus": "NOT_SIGNED",
        "sendStatus": "SENT"
      }
    ],
    "Recipient": [
      {
        "id": 52,
        "documentId": 10,
        "templateId": null,
        "email": "signer@example.com",
        "name": "John Doe",
        "token": "vbT8hi3jKQmrFP_LN1WcS",
        "documentDeletedAt": null,
        "expiresAt": null,
        "expirationNotifiedAt": null,
        "signedAt": null,
        "authOptions": null,
        "signingOrder": 1,
        "rejectionReason": null,
        "role": "SIGNER",
        "readStatus": "NOT_OPENED",
        "signingStatus": "NOT_SIGNED",
        "sendStatus": "SENT"
      }
    ]
  },
  "createdAt": "2024-04-22T11:48:07.945Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

document.opened

Triggered when a recipient opens the document for the first time.

Event name: DOCUMENT_OPENED

The recipient's readStatus changes to OPENED.

{
  "event": "DOCUMENT_OPENED",
  "payload": {
    "id": 10,
    "status": "PENDING",
    "title": "contract.pdf",
    "source": "DOCUMENT",
    "recipients": [
      {
        "id": 52,
        "email": "signer@example.com",
        "name": "John Doe",
        "role": "SIGNER",
        "readStatus": "OPENED",
        "signingStatus": "NOT_SIGNED",
        "sendStatus": "SENT"
      }
    ]
  },
  "createdAt": "2024-04-22T11:50:26.174Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

document.signed

Triggered when a recipient signs the document. This fires for each individual signature, not just when the document is fully completed.

Event name: DOCUMENT_SIGNED

The recipient's signingStatus changes to SIGNED and signedAt is populated.

{
  "event": "DOCUMENT_SIGNED",
  "payload": {
    "id": 10,
    "status": "COMPLETED",
    "title": "contract.pdf",
    "source": "DOCUMENT",
    "completedAt": "2024-04-22T11:52:05.707Z",
    "recipients": [
      {
        "id": 51,
        "email": "signer@example.com",
        "name": "John Doe",
        "role": "SIGNER",
        "signedAt": "2024-04-22T11:52:05.688Z",
        "readStatus": "OPENED",
        "signingStatus": "SIGNED",
        "sendStatus": "SENT"
      }
    ]
  },
  "createdAt": "2024-04-22T11:52:18.577Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

document.recipient.completed

Triggered when an individual recipient completes their required action (signing, approving, or viewing). This is useful for tracking per-recipient progress in documents with multiple recipients.

Event name: DOCUMENT_RECIPIENT_COMPLETED

{
  "event": "DOCUMENT_RECIPIENT_COMPLETED",
  "payload": {
    "id": 10,
    "status": "PENDING",
    "title": "contract.pdf",
    "source": "DOCUMENT",
    "recipients": [
      {
        "id": 52,
        "email": "signer@example.com",
        "name": "John Doe",
        "role": "SIGNER",
        "signedAt": "2024-04-22T11:52:05.688Z",
        "readStatus": "OPENED",
        "signingStatus": "SIGNED",
        "sendStatus": "SENT"
      }
    ]
  },
  "createdAt": "2024-04-22T11:52:06.000Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

document.completed

Triggered when all recipients have completed their required actions.

Event name: DOCUMENT_COMPLETED

The document status changes to COMPLETED and completedAt is set.

{
  "event": "DOCUMENT_COMPLETED",
  "payload": {
    "id": 10,
    "externalId": null,
    "userId": 1,
    "authOptions": null,
    "formValues": null,
    "visibility": "EVERYONE",
    "title": "contract.pdf",
    "status": "COMPLETED",
    "createdAt": "2024-04-22T11:44:43.341Z",
    "updatedAt": "2024-04-22T11:52:05.708Z",
    "completedAt": "2024-04-22T11:52:05.707Z",
    "deletedAt": null,
    "teamId": null,
    "templateId": null,
    "source": "DOCUMENT",
    "documentMeta": {
      "id": "doc_meta_123",
      "subject": "Please sign this document",
      "message": "Hello, please review and sign this document.",
      "timezone": "UTC",
      "password": null,
      "dateFormat": "MM/DD/YYYY",
      "redirectUrl": null,
      "signingOrder": "PARALLEL",
      "allowDictateNextSigner": false,
      "typedSignatureEnabled": true,
      "uploadSignatureEnabled": true,
      "drawSignatureEnabled": true,
      "language": "en",
      "distributionMethod": "EMAIL",
      "emailSettings": null
    },
    "recipients": [
      {
        "id": 50,
        "documentId": 10,
        "templateId": null,
        "email": "reviewer@example.com",
        "name": "Jane Smith",
        "token": "vbT8hi3jKQmrFP_LN1WcS",
        "documentDeletedAt": null,
        "expiresAt": null,
        "expirationNotifiedAt": null,
        "signedAt": "2024-04-22T11:51:10.055Z",
        "authOptions": {
          "accessAuth": null,
          "actionAuth": null
        },
        "signingOrder": 1,
        "rejectionReason": null,
        "role": "VIEWER",
        "readStatus": "OPENED",
        "signingStatus": "SIGNED",
        "sendStatus": "SENT"
      },
      {
        "id": 51,
        "documentId": 10,
        "templateId": null,
        "email": "signer@example.com",
        "name": "John Doe",
        "token": "HkrptwS42ZBXdRKj1TyUo",
        "documentDeletedAt": null,
        "expiresAt": null,
        "expirationNotifiedAt": null,
        "signedAt": "2024-04-22T11:52:05.688Z",
        "authOptions": {
          "accessAuth": null,
          "actionAuth": null
        },
        "signingOrder": 2,
        "rejectionReason": null,
        "role": "SIGNER",
        "readStatus": "OPENED",
        "signingStatus": "SIGNED",
        "sendStatus": "SENT"
      }
    ],
    "Recipient": [
      {
        "id": 50,
        "documentId": 10,
        "templateId": null,
        "email": "reviewer@example.com",
        "name": "Jane Smith",
        "token": "vbT8hi3jKQmrFP_LN1WcS",
        "documentDeletedAt": null,
        "expiresAt": null,
        "expirationNotifiedAt": null,
        "signedAt": "2024-04-22T11:51:10.055Z",
        "authOptions": {
          "accessAuth": null,
          "actionAuth": null
        },
        "signingOrder": 1,
        "rejectionReason": null,
        "role": "VIEWER",
        "readStatus": "OPENED",
        "signingStatus": "SIGNED",
        "sendStatus": "SENT"
      },
      {
        "id": 51,
        "documentId": 10,
        "templateId": null,
        "email": "signer@example.com",
        "name": "John Doe",
        "token": "HkrptwS42ZBXdRKj1TyUo",
        "documentDeletedAt": null,
        "expiresAt": null,
        "expirationNotifiedAt": null,
        "signedAt": "2024-04-22T11:52:05.688Z",
        "authOptions": {
          "accessAuth": null,
          "actionAuth": null
        },
        "signingOrder": 2,
        "rejectionReason": null,
        "role": "SIGNER",
        "readStatus": "OPENED",
        "signingStatus": "SIGNED",
        "sendStatus": "SENT"
      }
    ]
  },
  "createdAt": "2024-04-22T11:52:18.277Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

document.rejected

Triggered when a recipient rejects the document.

Event name: DOCUMENT_REJECTED

The recipient's signingStatus changes to REJECTED and rejectionReason contains their reason.

{
  "event": "DOCUMENT_REJECTED",
  "payload": {
    "id": 10,
    "status": "PENDING",
    "title": "contract.pdf",
    "source": "DOCUMENT",
    "recipients": [
      {
        "id": 52,
        "email": "signer@example.com",
        "name": "John Doe",
        "role": "SIGNER",
        "signedAt": "2024-04-22T11:48:07.569Z",
        "rejectionReason": "I do not agree with the terms",
        "readStatus": "OPENED",
        "signingStatus": "REJECTED",
        "sendStatus": "SENT"
      }
    ]
  },
  "createdAt": "2024-04-22T11:48:07.945Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

document.cancelled

Triggered when the document owner or a team member deletes a document. Draft and pending documents are hard-deleted, while completed documents are soft-deleted.

This event is not triggered when a recipient hides a document from their inbox.

Event name: DOCUMENT_CANCELLED

{
  "event": "DOCUMENT_CANCELLED",
  "payload": {
    "id": 7,
    "externalId": null,
    "userId": 3,
    "authOptions": null,
    "formValues": null,
    "visibility": "EVERYONE",
    "title": "contract.pdf",
    "status": "PENDING",
    "createdAt": "2025-01-27T11:02:14.393Z",
    "updatedAt": "2025-01-27T11:03:16.387Z",
    "completedAt": null,
    "deletedAt": null,
    "teamId": null,
    "templateId": null,
    "source": "DOCUMENT",
    "documentMeta": {
      "id": "cm6exvn96006ji02rqvzjvwoy",
      "subject": "",
      "message": "",
      "timezone": "Etc/UTC",
      "password": null,
      "dateFormat": "yyyy-MM-dd hh:mm a",
      "redirectUrl": "",
      "signingOrder": "PARALLEL",
      "allowDictateNextSigner": false,
      "typedSignatureEnabled": true,
      "uploadSignatureEnabled": true,
      "drawSignatureEnabled": true,
      "language": "en",
      "distributionMethod": "EMAIL",
      "emailSettings": null
    },
    "recipients": [
      {
        "id": 7,
        "documentId": 7,
        "templateId": null,
        "email": "signer@example.com",
        "name": "John Doe",
        "token": "XkKx1HCs6Znm2UBJA2j6o",
        "documentDeletedAt": null,
        "expiresAt": null,
        "expirationNotifiedAt": null,
        "signedAt": null,
        "authOptions": { "accessAuth": null, "actionAuth": null },
        "signingOrder": 1,
        "rejectionReason": null,
        "role": "SIGNER",
        "readStatus": "NOT_OPENED",
        "signingStatus": "NOT_SIGNED",
        "sendStatus": "SENT"
      }
    ],
    "Recipient": [
      {
        "id": 7,
        "documentId": 7,
        "templateId": null,
        "email": "signer@example.com",
        "name": "John Doe",
        "token": "XkKx1HCs6Znm2UBJA2j6o",
        "documentDeletedAt": null,
        "expiresAt": null,
        "expirationNotifiedAt": null,
        "signedAt": null,
        "authOptions": { "accessAuth": null, "actionAuth": null },
        "signingOrder": 1,
        "rejectionReason": null,
        "role": "SIGNER",
        "readStatus": "NOT_OPENED",
        "signingStatus": "NOT_SIGNED",
        "sendStatus": "SENT"
      }
    ]
  },
  "createdAt": "2025-01-27T11:03:27.730Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

document.reminder.sent

Triggered when a reminder email is sent to a recipient who has not yet completed their action.

Event name: DOCUMENT_REMINDER_SENT

{
  "event": "DOCUMENT_REMINDER_SENT",
  "payload": {
    "id": 10,
    "status": "PENDING",
    "title": "contract.pdf",
    "source": "DOCUMENT",
    "recipients": [
      {
        "id": 52,
        "email": "signer@example.com",
        "name": "John Doe",
        "role": "SIGNER",
        "readStatus": "NOT_OPENED",
        "signingStatus": "NOT_SIGNED",
        "sendStatus": "SENT"
      }
    ]
  },
  "createdAt": "2024-04-23T09:00:00.000Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

Template Events

Template events track changes to reusable document templates. Template payloads use the same structure as document payloads, with source set to TEMPLATE and templateId populated.

template.created

Triggered when a new template is created.

Event name: TEMPLATE_CREATED

{
  "event": "TEMPLATE_CREATED",
  "payload": {
    "id": 10,
    "title": "My Template",
    "status": "DRAFT",
    "templateId": 10,
    "source": "TEMPLATE",
    "recipients": []
  },
  "createdAt": "2024-04-22T11:44:44.779Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

template.updated

Triggered when a template's settings, recipients, or fields are modified.

Event name: TEMPLATE_UPDATED

{
  "event": "TEMPLATE_UPDATED",
  "payload": {
    "id": 10,
    "title": "My Updated Template",
    "status": "DRAFT",
    "templateId": 10,
    "source": "TEMPLATE",
    "recipients": []
  },
  "createdAt": "2024-04-22T12:00:00.000Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

template.deleted

Triggered when a template is deleted.

Event name: TEMPLATE_DELETED

{
  "event": "TEMPLATE_DELETED",
  "payload": {
    "id": 10,
    "title": "Deleted Template",
    "status": "DRAFT",
    "templateId": 10,
    "source": "TEMPLATE",
    "recipients": []
  },
  "createdAt": "2024-04-22T13:00:00.000Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

template.used

Triggered when a document is created from a template. This event fires alongside document.created, giving you a way to specifically track template usage.

Event name: TEMPLATE_USED

{
  "event": "TEMPLATE_USED",
  "payload": {
    "id": 10,
    "title": "Document from Template",
    "status": "DRAFT",
    "templateId": 10,
    "source": "TEMPLATE",
    "recipients": []
  },
  "createdAt": "2024-04-22T14:00:00.000Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

Event Summary

Document Events

EventTriggerKey Changes
DOCUMENT_CREATEDDocument uploaded or created from templatestatus: "DRAFT"
DOCUMENT_SENTDocument sent to recipientsstatus: "PENDING", recipients sendStatus: "SENT"
DOCUMENT_OPENEDRecipient opens document for the first timeRecipient readStatus: "OPENED"
DOCUMENT_SIGNEDRecipient signs documentRecipient signingStatus: "SIGNED", signedAt set
DOCUMENT_RECIPIENT_COMPLETEDRecipient completes their actionRecipient signingStatus: "SIGNED", signedAt set
DOCUMENT_COMPLETEDAll recipients complete actionsstatus: "COMPLETED", completedAt set
DOCUMENT_REJECTEDRecipient rejects documentRecipient signingStatus: "REJECTED", rejectionReason set
DOCUMENT_CANCELLEDOwner or team member deletes documentDocument cancelled or deleted
DOCUMENT_REMINDER_SENTReminder email sent to recipientNo status changes

Template Events

EventTriggerKey Changes
TEMPLATE_CREATEDNew template createdsource: "TEMPLATE"
TEMPLATE_UPDATEDTemplate settings or fields modifiedsource: "TEMPLATE"
TEMPLATE_DELETEDTemplate deletedsource: "TEMPLATE"
TEMPLATE_USEDDocument created from templatesource: "TEMPLATE"

Handling Events

When processing webhook events:

Verify the signature — Check the X-Documenso-Secret header matches your configured secret

Check event type — Use the event field to determine the action

Process idempotently — Webhooks may be retried, so handle duplicate events

Respond quickly — Return a 200 status code within 30 seconds

app.post('/webhook', (req, res) => {
  const secret = req.headers['x-documenso-secret'];

  if (secret !== process.env.WEBHOOK_SECRET) {
    return res.status(401).send('Unauthorized');
  }

  const { event, payload } = req.body;

  switch (event) {
    case 'DOCUMENT_COMPLETED':
      console.log(`Document ${payload.id} completed`);
      break;
    case 'DOCUMENT_RECIPIENT_COMPLETED':
      const signer = payload.recipients.find((r) => r.signingStatus === 'SIGNED');
      console.log(`${signer?.name} completed their action on document ${payload.id}`);
      break;
    case 'DOCUMENT_SIGNED':
      console.log(`Signature added to document ${payload.id}`);
      break;
    case 'DOCUMENT_REJECTED':
      const rejecter = payload.recipients.find((r) => r.signingStatus === 'REJECTED');
      console.log(`${rejecter?.name} rejected: ${rejecter?.rejectionReason}`);
      break;
    case 'TEMPLATE_USED':
      console.log(`Template ${payload.templateId} used to create document ${payload.id}`);
      break;
  }

  res.status(200).send('OK');
});

See Also

Webhook Setup

Configure webhooks to receive real-time notifications about document events.

Webhook Verification

Verify webhook signatures for security.

On this page

Event Payload StructureTop-Level FieldsPayload FieldsDocument Metadata FieldsRecipient FieldsDocument Lifecycle Eventsdocument.createddocument.sentdocument.openeddocument.signeddocument.recipient.completeddocument.completeddocument.rejecteddocument.cancelleddocument.reminder.sentTemplate Eventstemplate.createdtemplate.updatedtemplate.deletedtemplate.usedEvent SummaryDocument EventsTemplate EventsHandling EventsSee Also