# Webhook events and payloads

> SignWith sends these events to your webhook endpoints. Each one wraps the object it is about, in the same shape the API returns.

Source: https://signwith.co/docs/api/webhooks/events · Updated 2026-10-02

Every event has the same envelope: `id`, `type`, `created_at` and `data`. See [webhooks](https://signwith.co/docs/api/webhooks) for the headers, retries and how to add an endpoint, and [verify webhook signatures](https://signwith.co/docs/api/webhooks/verify-signatures) before you trust a payload.

## `signature_request.created`

A signature request was sent.

Sent when a signature request is created — from the API, the dashboard or a shared signing
link. `data` is a [SignatureRequest](#/components/schemas/SignatureRequest).

```json
{
  "id": "evt_4Kc9QmT2vXw8ZpLs7NbR3yAd",
  "type": "signature_request.created",
  "created_at": "2026-09-27T09:00:01Z",
  "data": {
    "object": "signature_request",
    "id": 4812,
    "status": "sent",
    "template": {
      "id": 311,
      "name": "Residential lease"
    },
    "signing_order": "sequential",
    "source": "api",
    "created_by": {
      "id": 42,
      "email": "ada@acme.co",
      "name": "Ada Lovelace"
    },
    "signers": [
      {
        "object": "signer",
        "id": 9120,
        "signature_request_id": 4812,
        "role": "Tenant",
        "name": "Grace Hopper",
        "email": "grace@example.com",
        "phone": null,
        "external_id": "cust_8841",
        "metadata": {},
        "status": "sent",
        "signing_url": "https://app.signwith.co/s/Hn3cW8yRk2Qe",
        "sent_at": "2026-09-27T09:00:02Z",
        "viewed_at": null,
        "signed_at": null,
        "declined_at": null,
        "created_at": "2026-09-27T09:00:01Z",
        "updated_at": "2026-09-27T09:00:02Z",
        "values": []
      }
    ],
    "expires_at": null,
    "completed_at": null,
    "canceled_at": null,
    "created_at": "2026-09-27T09:00:01Z",
    "updated_at": "2026-09-27T09:00:01Z"
  }
}
```

## `signature_request.completed`

Every signer has signed.

Sent when the last signer signs. `data` is a [SignatureRequest](#/components/schemas/SignatureRequest)
with `status: completed`, including links to the signed documents and audit trail. If a link
is `null`, fetch the signature request again shortly afterwards. Subscribed by default for new
endpoints.

```json
{
  "id": "evt_9RtB2wLx5HqN8cVm3KpZ7sYe",
  "type": "signature_request.completed",
  "created_at": "2026-09-27T10:15:00Z",
  "data": {
    "object": "signature_request",
    "id": 4812,
    "status": "completed",
    "template": {
      "id": 311,
      "name": "Residential lease"
    },
    "signing_order": "sequential",
    "source": "api",
    "created_by": {
      "id": 42,
      "email": "ada@acme.co",
      "name": "Ada Lovelace"
    },
    "signers": [
      {
        "object": "signer",
        "id": 9120,
        "signature_request_id": 4812,
        "role": "Tenant",
        "name": "Grace Hopper",
        "email": "grace@example.com",
        "phone": null,
        "external_id": "cust_8841",
        "metadata": {
          "crm_deal_id": "D-2291"
        },
        "status": "signed",
        "signing_url": null,
        "sent_at": "2026-09-27T09:00:02Z",
        "viewed_at": "2026-09-27T09:41:18Z",
        "signed_at": "2026-09-27T09:44:51Z",
        "declined_at": null,
        "created_at": "2026-09-27T09:00:01Z",
        "updated_at": "2026-09-27T09:44:51Z",
        "values": [
          {
            "field": "Tenant name",
            "value": "Grace Hopper"
          },
          {
            "field": "Monthly rent",
            "value": "2150"
          },
          {
            "field": "Start date",
            "value": "2026-11-01"
          },
          {
            "field": "Pets",
            "value": "Cat"
          },
          {
            "field": "Tenant signature",
            "value": "https://app.signwith.co/file/eyJfcmFpbHMiOnsiZGF0YSI6NTUxfX0/signature.png"
          }
        ],
        "documents": [
          {
            "name": "Lease agreement",
            "url": "https://app.signwith.co/file/eyJfcmFpbHMiOnsiZGF0YSI6NTUyfX0/lease-agreement.pdf"
          }
        ]
      },
      {
        "object": "signer",
        "id": 9121,
        "signature_request_id": 4812,
        "role": "Landlord",
        "name": "Ada Lovelace",
        "email": "ada@acme.co",
        "phone": null,
        "external_id": null,
        "metadata": {},
        "status": "signed",
        "signing_url": null,
        "sent_at": "2026-09-27T09:44:53Z",
        "viewed_at": "2026-09-27T10:12:30Z",
        "signed_at": "2026-09-27T10:14:58Z",
        "declined_at": null,
        "created_at": "2026-09-27T09:00:01Z",
        "updated_at": "2026-09-27T10:14:58Z",
        "values": [
          {
            "field": "Landlord signature",
            "value": "https://app.signwith.co/file/eyJfcmFpbHMiOnsiZGF0YSI6NTYwfX0/signature.png"
          }
        ],
        "documents": [
          {
            "name": "Lease agreement",
            "url": "https://app.signwith.co/file/eyJfcmFpbHMiOnsiZGF0YSI6NTYxfX0/lease-agreement.pdf"
          }
        ]
      }
    ],
    "expires_at": "2026-10-27T00:00:00Z",
    "completed_at": "2026-09-27T10:14:58Z",
    "canceled_at": null,
    "created_at": "2026-09-27T09:00:01Z",
    "updated_at": "2026-09-27T10:14:58Z",
    "documents": [
      {
        "name": "Lease agreement",
        "url": "https://app.signwith.co/file/eyJfcmFpbHMiOnsiZGF0YSI6NTYxfX0/lease-agreement.pdf"
      }
    ],
    "audit_trail_url": "https://app.signwith.co/file/eyJfcmFpbHMiOnsiZGF0YSI6NTYyfX0/audit-trail.pdf",
    "combined_document_url": null
  }
}
```

## `signature_request.canceled`

A signature request was canceled.

Sent when a signature request is canceled from the API or the dashboard. `data` is a
[SignatureRequest](#/components/schemas/SignatureRequest) with `status: canceled`.

```json
{
  "id": "evt_2HsW7kQp9ZxT4mBn6LcR8vYd",
  "type": "signature_request.canceled",
  "created_at": "2026-09-28T08:30:12Z",
  "data": {
    "object": "signature_request",
    "id": 4812,
    "status": "canceled",
    "template": {
      "id": 311,
      "name": "Residential lease"
    },
    "signing_order": "sequential",
    "source": "api",
    "created_by": {
      "id": 42,
      "email": "ada@acme.co",
      "name": "Ada Lovelace"
    },
    "signers": [
      {
        "object": "signer",
        "id": 9120,
        "signature_request_id": 4812,
        "role": "Tenant",
        "name": "Grace Hopper",
        "email": "grace@example.com",
        "phone": null,
        "external_id": "cust_8841",
        "metadata": {},
        "status": "viewed",
        "signing_url": "https://app.signwith.co/s/Hn3cW8yRk2Qe",
        "sent_at": "2026-09-27T09:00:02Z",
        "viewed_at": "2026-09-27T09:41:18Z",
        "signed_at": null,
        "declined_at": null,
        "created_at": "2026-09-27T09:00:01Z",
        "updated_at": "2026-09-27T09:41:18Z",
        "values": []
      }
    ],
    "expires_at": null,
    "completed_at": null,
    "canceled_at": "2026-09-28T08:30:12Z",
    "created_at": "2026-09-27T09:00:01Z",
    "updated_at": "2026-09-28T08:30:12Z"
  }
}
```

## `signer.viewed`

A signer opened the document.

Sent when a signer opens their signing link. `data` is a [Signer](#/components/schemas/Signer)
plus a short `signature_request` summary.

```json
{
  "id": "evt_6NpQ3xVb8KsR2tLm9WcZ4yHe",
  "type": "signer.viewed",
  "created_at": "2026-09-27T09:41:18Z",
  "data": {
    "object": "signer",
    "id": 9120,
    "signature_request_id": 4812,
    "role": "Tenant",
    "name": "Grace Hopper",
    "email": "grace@example.com",
    "phone": null,
    "external_id": "cust_8841",
    "metadata": {},
    "status": "viewed",
    "signing_url": "https://app.signwith.co/s/Hn3cW8yRk2Qe",
    "sent_at": "2026-09-27T09:00:02Z",
    "viewed_at": "2026-09-27T09:41:18Z",
    "signed_at": null,
    "declined_at": null,
    "created_at": "2026-09-27T09:00:01Z",
    "updated_at": "2026-09-27T09:41:18Z",
    "values": [
      {
        "field": "Tenant name",
        "value": "Grace Hopper"
      }
    ],
    "signature_request": {
      "id": 4812,
      "status": "sent"
    }
  }
}
```

## `signer.started`

A signer started filling in fields.

Sent when a signer saves their first field value. Useful for showing "in progress" in your UI.
`data` is a [Signer](#/components/schemas/Signer) plus a short `signature_request` summary.

```json
{
  "id": "evt_3TmK8vRx2NqW7pLb5HcZ9sYd",
  "type": "signer.started",
  "created_at": "2026-09-27T09:42:03Z",
  "data": {
    "object": "signer",
    "id": 9120,
    "signature_request_id": 4812,
    "role": "Tenant",
    "name": "Grace Hopper",
    "email": "grace@example.com",
    "phone": null,
    "external_id": "cust_8841",
    "metadata": {},
    "status": "viewed",
    "signing_url": "https://app.signwith.co/s/Hn3cW8yRk2Qe",
    "sent_at": "2026-09-27T09:00:02Z",
    "viewed_at": "2026-09-27T09:41:18Z",
    "signed_at": null,
    "declined_at": null,
    "created_at": "2026-09-27T09:00:01Z",
    "updated_at": "2026-09-27T09:42:03Z",
    "values": [
      {
        "field": "Tenant name",
        "value": "Grace Hopper"
      },
      {
        "field": "Phone number",
        "value": "+14155550123"
      }
    ],
    "signature_request": {
      "id": 4812,
      "status": "sent"
    }
  }
}
```

## `signer.signed`

A signer finished signing.

Sent when a signer completes their part. `data` is a [Signer](#/components/schemas/Signer)
with `status: signed`, their field values and signed documents, plus a short
`signature_request` summary. Subscribed by default for new endpoints.

```json
{
  "id": "evt_7Qm2Vt9sKd3LpXa8RzYw1bNc",
  "type": "signer.signed",
  "created_at": "2026-09-27T09:44:51Z",
  "data": {
    "object": "signer",
    "id": 9120,
    "signature_request_id": 4812,
    "role": "Tenant",
    "name": "Grace Hopper",
    "email": "grace@example.com",
    "phone": null,
    "external_id": "cust_8841",
    "metadata": {
      "crm_deal_id": "D-2291"
    },
    "status": "signed",
    "signing_url": null,
    "sent_at": "2026-09-27T09:00:02Z",
    "viewed_at": "2026-09-27T09:41:18Z",
    "signed_at": "2026-09-27T09:44:51Z",
    "declined_at": null,
    "created_at": "2026-09-27T09:00:01Z",
    "updated_at": "2026-09-27T09:44:51Z",
    "values": [
      {
        "field": "Tenant name",
        "value": "Grace Hopper"
      },
      {
        "field": "Tenant signature",
        "value": "https://app.signwith.co/file/eyJfcmFpbHMiOnsiZGF0YSI6NTUxfX0/signature.png"
      }
    ],
    "documents": [
      {
        "name": "Lease agreement",
        "url": "https://app.signwith.co/file/eyJfcmFpbHMiOnsiZGF0YSI6NTUyfX0/lease-agreement.pdf"
      }
    ],
    "signature_request": {
      "id": 4812,
      "status": "in_progress"
    }
  }
}
```

## `signer.declined`

A signer declined to sign.

Sent when a signer declines. The signature request's status becomes `declined`. `data` is a
[Signer](#/components/schemas/Signer) plus a short `signature_request` summary. Subscribed by
default for new endpoints.

```json
{
  "id": "evt_8LwR4nKx6TqB2mVp9ZcH3sYe",
  "type": "signer.declined",
  "created_at": "2026-09-27T12:05:40Z",
  "data": {
    "object": "signer",
    "id": 9121,
    "signature_request_id": 4812,
    "role": "Landlord",
    "name": "Ada Lovelace",
    "email": "ada@acme.co",
    "phone": null,
    "external_id": null,
    "metadata": {},
    "status": "declined",
    "signing_url": null,
    "sent_at": "2026-09-27T09:44:53Z",
    "viewed_at": "2026-09-27T12:03:11Z",
    "signed_at": null,
    "declined_at": "2026-09-27T12:05:40Z",
    "created_at": "2026-09-27T09:00:01Z",
    "updated_at": "2026-09-27T12:05:40Z",
    "values": [],
    "signature_request": {
      "id": 4812,
      "status": "declined"
    }
  }
}
```

## `template.created`

A template was created.

Sent when a template is created — uploaded in the dashboard, created through the API, or
duplicated. `data` is a [Template](#/components/schemas/Template).

```json
{
  "id": "evt_5KpT9wRm3XqN7vLb2HcZ8sYd",
  "type": "template.created",
  "created_at": "2026-09-20T09:12:44Z",
  "data": {
    "object": "template",
    "id": 311,
    "name": "Residential lease",
    "external_id": "lease-v3",
    "folder": "Leasing",
    "roles": [
      "Tenant",
      "Landlord"
    ],
    "edit_url": "https://app.signwith.co/templates/311/edit",
    "created_by": {
      "id": 42,
      "email": "ada@acme.co",
      "name": "Ada Lovelace"
    },
    "archived_at": null,
    "created_at": "2026-09-20T09:12:44Z",
    "updated_at": "2026-09-21T16:03:10Z",
    "fields": [
      {
        "id": "0f9c2b7e-5d1a-4e8b-9a61-3c2e7d4f1a90",
        "name": "Tenant name",
        "type": "text",
        "role": "Tenant",
        "required": true
      },
      {
        "id": "6a3e1d42-8b7c-4f19-a0d5-2e9b4c7f8a13",
        "name": "Monthly rent",
        "type": "number",
        "role": "Tenant",
        "required": true
      },
      {
        "id": "b2d8f4a1-3c6e-4a7b-8d92-5f1e0c3a9b76",
        "name": "Start date",
        "type": "date",
        "role": "Tenant",
        "required": true
      },
      {
        "id": "91c7e3b5-2a4d-4f8e-b610-7d3a5c9e2f48",
        "name": "Pets",
        "type": "select",
        "role": "Tenant",
        "required": false,
        "options": [
          "None",
          "Cat",
          "Dog"
        ]
      },
      {
        "id": "4e8a2c6f-9b1d-4a3e-8c57-1f6d0b9e3a24",
        "name": "Tenant signature",
        "type": "signature",
        "role": "Tenant",
        "required": true
      },
      {
        "id": "c5f1a9d3-7e2b-4c8a-9f60-3b8e4d2a7c15",
        "name": "Landlord signature",
        "type": "signature",
        "role": "Landlord",
        "required": true
      }
    ],
    "documents": [
      {
        "id": 7730,
        "name": "Lease agreement",
        "url": "https://app.signwith.co/file/eyJfcmFpbHMiOnsiZGF0YSI6MTIzfX0/lease-agreement.pdf",
        "preview_image_url": "https://app.signwith.co/file/eyJfcmFpbHMiOnsiZGF0YSI6MTI0fX0/0.jpg"
      }
    ]
  }
}
```

## `template.updated`

A template was changed.

Sent when a template's name, folder, roles, fields or documents change. `data` is a
[Template](#/components/schemas/Template).

```json
{
  "id": "evt_1MvK6pTx8RqW3nLb9HcZ2sYe",
  "type": "template.updated",
  "created_at": "2026-09-21T16:03:10Z",
  "data": {
    "object": "template",
    "id": 311,
    "name": "Residential lease",
    "external_id": "lease-v3",
    "folder": "Leasing",
    "roles": [
      "Tenant",
      "Landlord"
    ],
    "edit_url": "https://app.signwith.co/templates/311/edit",
    "created_by": {
      "id": 42,
      "email": "ada@acme.co",
      "name": "Ada Lovelace"
    },
    "archived_at": null,
    "created_at": "2026-09-20T09:12:44Z",
    "updated_at": "2026-09-21T16:03:10Z",
    "fields": [
      {
        "id": "0f9c2b7e-5d1a-4e8b-9a61-3c2e7d4f1a90",
        "name": "Tenant name",
        "type": "text",
        "role": "Tenant",
        "required": true
      },
      {
        "id": "6a3e1d42-8b7c-4f19-a0d5-2e9b4c7f8a13",
        "name": "Monthly rent",
        "type": "number",
        "role": "Tenant",
        "required": true
      },
      {
        "id": "b2d8f4a1-3c6e-4a7b-8d92-5f1e0c3a9b76",
        "name": "Start date",
        "type": "date",
        "role": "Tenant",
        "required": true
      },
      {
        "id": "91c7e3b5-2a4d-4f8e-b610-7d3a5c9e2f48",
        "name": "Pets",
        "type": "select",
        "role": "Tenant",
        "required": false,
        "options": [
          "None",
          "Cat",
          "Dog"
        ]
      },
      {
        "id": "4e8a2c6f-9b1d-4a3e-8c57-1f6d0b9e3a24",
        "name": "Tenant signature",
        "type": "signature",
        "role": "Tenant",
        "required": true
      },
      {
        "id": "c5f1a9d3-7e2b-4c8a-9f60-3b8e4d2a7c15",
        "name": "Landlord signature",
        "type": "signature",
        "role": "Landlord",
        "required": true
      }
    ],
    "documents": [
      {
        "id": 7730,
        "name": "Lease agreement",
        "url": "https://app.signwith.co/file/eyJfcmFpbHMiOnsiZGF0YSI6MTIzfX0/lease-agreement.pdf",
        "preview_image_url": "https://app.signwith.co/file/eyJfcmFpbHMiOnsiZGF0YSI6MTI0fX0/0.jpg"
      }
    ]
  }
}
```

## `template.archived`

A template was archived.

Sent when a template is archived. `data` is a [Template](#/components/schemas/Template) with
`archived_at` set.

```json
{
  "id": "evt_4NqB8vKx2TmR6pLw9HcZ3sYd",
  "type": "template.archived",
  "created_at": "2026-09-29T14:20:00Z",
  "data": {
    "object": "template",
    "id": 311,
    "name": "Residential lease",
    "external_id": "lease-v3",
    "folder": "Leasing",
    "roles": [
      "Tenant",
      "Landlord"
    ],
    "edit_url": "https://app.signwith.co/templates/311/edit",
    "created_by": {
      "id": 42,
      "email": "ada@acme.co",
      "name": "Ada Lovelace"
    },
    "archived_at": "2026-09-29T14:20:00Z",
    "created_at": "2026-09-20T09:12:44Z",
    "updated_at": "2026-09-29T14:20:00Z",
    "fields": [],
    "documents": []
  }
}
```

## `webhook.test`

Test event from the dashboard.

Sent immediately when you click **Send test event** on a webhook's settings page, regardless
of which events the endpoint is subscribed to. It is not retried. `data` has the same shape as
a `signer.signed` event, using the most recently signed signer in your account — or an empty
object if nobody has signed yet. Use it to check that your endpoint is reachable and that
signature verification works; don't treat it as a real signing.

Account with signed documents:

```json
{
  "id": "evt_9ZcT3mKx7RqB2vLp8HnW4sYd",
  "type": "webhook.test",
  "created_at": "2026-09-27T13:00:00Z",
  "data": {
    "object": "signer",
    "id": 9120,
    "signature_request_id": 4812,
    "role": "Tenant",
    "name": "Grace Hopper",
    "email": "grace@example.com",
    "phone": null,
    "external_id": "cust_8841",
    "metadata": {
      "crm_deal_id": "D-2291"
    },
    "status": "signed",
    "signing_url": null,
    "sent_at": "2026-09-27T09:00:02Z",
    "viewed_at": "2026-09-27T09:41:18Z",
    "signed_at": "2026-09-27T09:44:51Z",
    "declined_at": null,
    "created_at": "2026-09-27T09:00:01Z",
    "updated_at": "2026-09-27T09:44:51Z",
    "values": [
      {
        "field": "Tenant name",
        "value": "Grace Hopper"
      },
      {
        "field": "Tenant signature",
        "value": "https://app.signwith.co/file/eyJfcmFpbHMiOnsiZGF0YSI6NTUxfX0/signature.png"
      }
    ],
    "documents": [
      {
        "name": "Lease agreement",
        "url": "https://app.signwith.co/file/eyJfcmFpbHMiOnsiZGF0YSI6NTUyfX0/lease-agreement.pdf"
      }
    ],
    "signature_request": {
      "id": 4812,
      "status": "in_progress"
    }
  }
}
```

New account:

```json
{
  "id": "evt_2BxK8nTq5RmW7vLp3HcZ9sYe",
  "type": "webhook.test",
  "created_at": "2026-09-27T13:00:00Z",
  "data": {}
}
```