Skip to content
SignWithDocs
Esc
  • Developer docs homeDocs
  • ChangelogDocs
  • OverviewREST API · Get started
  • Quick startREST API · Get started
  • Text tagsREST API · Get started
  • AuthenticationREST API · Get started
  • Making requestsREST API · Get started
  • ErrorsREST API · Get started

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.

MarkdownAsk ChatGPTAsk Claude

Updated

Every event has the same envelope: id, type, created_at and data. See webhooks for the headers, retries and how to add an endpoint, and verify webhook 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.

Fields of data: see the signature request object.

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": "[email protected]",
      "name": "Ada Lovelace"
    },
    "signers": [
      {
        "object": "signer",
        "id": 9120,
        "signature_request_id": 4812,
        "role": "Tenant",
        "name": "Grace Hopper",
        "email": "[email protected]",
        "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 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.

Fields of data: see the signature request object.

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": "[email protected]",
      "name": "Ada Lovelace"
    },
    "signers": [
      {
        "object": "signer",
        "id": 9120,
        "signature_request_id": 4812,
        "role": "Tenant",
        "name": "Grace Hopper",
        "email": "[email protected]",
        "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": "[email protected]",
        "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 with status: canceled.

Fields of data: see the signature request object.

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": "[email protected]",
      "name": "Ada Lovelace"
    },
    "signers": [
      {
        "object": "signer",
        "id": 9120,
        "signature_request_id": 4812,
        "role": "Tenant",
        "name": "Grace Hopper",
        "email": "[email protected]",
        "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 plus a short signature_request summary.

Fields of data: see the signer object.

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": "[email protected]",
    "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 plus a short signature_request summary.

Fields of data: see the signer object.

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": "[email protected]",
    "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 with status: signed, their field values and signed documents, plus a short signature_request summary. Subscribed by default for new endpoints.

Fields of data: see the signer object.

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": "[email protected]",
    "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 plus a short signature_request summary. Subscribed by default for new endpoints.

Fields of data: see the signer object.

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": "[email protected]",
    "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.

Fields of data: see the template object.

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": "[email protected]",
      "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.

Fields of data: see the template object.

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": "[email protected]",
      "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 with archived_at set.

Fields of data: see the template object.

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": "[email protected]",
      "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.

Fields of data: see the signer object.

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": "[email protected]",
    "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": {}
}

Start building

The API and MCP server come with every account. 3 free documents a month, then pay per document.

Create accountGet API key