---
title: Webhooks
description: Receive real-time notifications for document and template events.
---

## How Webhooks Work

1. You configure a webhook URL in Documenso
2. When an event occurs, Documenso sends an HTTP POST to your URL
3. Your application processes the event and responds with 200 OK

Documenso supports webhook events for the full document lifecycle (created, sent, opened, signed, completed, rejected, cancelled), recipient-level events (recipient completed, reminder sent, recipient expired), and template events (created, updated, deleted, used).

---

## Getting Started

<Cards>
  <Card
    title="Setup"
    description="Configure webhook endpoints."
    href="/docs/developers/webhooks/setup"
  />
  <Card
    title="Events"
    description="Available webhook event types."
    href="/docs/developers/webhooks/events"
  />
  <Card
    title="Verification"
    description="Verify webhook signatures for security."
    href="/docs/developers/webhooks/verification"
  />
</Cards>

---

## Example Payload

```json
{
  "event": "DOCUMENT_COMPLETED",
  "payload": {
    "id": 123,
    "envelopeId": "envelope_abcdefhiklmnorst",
    "title": "Contract",
    "status": "COMPLETED",
    "completedAt": "2024-01-15T10:30:00.000Z",
    "recipients": [
      {
        "id": 1,
        "envelopeId": "envelope_abcdefhiklmnorst",
        "email": "signer@example.com",
        "signingStatus": "SIGNED"
      }
    ]
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}
```

`payload.id` is the legacy numeric v1 ID. Use `payload.envelopeId` as the canonical v2 identifier. Each recipient repeats `envelopeId` as the reliable parent link because the legacy `documentId` and `templateId` fields depend on the parent envelope type, leaving one of them null.

---

## See Also

- [Document Lifecycle](/docs/concepts/document-lifecycle) - Understanding document statuses
