Webhooks

Webhooks allow Inspakt to notify your system in real time when signing events occur — without polling. When a registered event is triggered, Inspakt sends an HTTP POST request to your endpoint with a JSON payload describing the event.

How it works

Register a webhook URL in the Inspakt customer panel under Settings → Integrations → Webhooks.
Inspakt sends a POST request to your URL whenever a registered event occurs.
Your endpoint should return a 2xx response. There is no retry on failure — if your endpoint is unavailable, the notification is not re-delivered.

caution

Webhook deliveries are best-effort. For critical workflows, always use the Get Envelope endpoint to verify state rather than relying solely on webhook receipt.

Payload structure

Every webhook delivery shares the same wrapper structure:

{
  "webhookId": "whk_...",
  "teamId": "team_...",
  "event": "envelope.finalized",
  "data": { ... }
}

Field	Type	Description
`webhookId`	string	ID of the webhook configuration that triggered this delivery.
`teamId`	string	ID of the team that owns the resource.
`event`	string	The event type. See the Event reference below.
`data`	object	Event-specific payload. Structure varies by event type.
`deprecated`	boolean	If `true`, this event format is deprecated and will be removed in a future version.

Event reference

`envelope.created`

Fired when a new envelope is created.

{
  "event": "envelope.created",
  "data": {
    "templateId": "tpl_...",
    "envelope": {
      "id": "env_...",
      "name": "Service Agreement — Acme Corp",
      "context": { "contractId": "CNT-001" }
    }
  }
}

Field	Description
`data.envelope.id`	ID of the created envelope.
`data.envelope.name`	Display name of the envelope.
`data.envelope.context`	The `context` object attached at creation.
`data.templateId`	Set if the envelope was created from a template.

`envelope.sent`

Fired when an envelope is dispatched to recipients.

{
  "event": "envelope.sent",
  "data": {
    "envelopeId": "env_...",
    "name": "Service Agreement — Acme Corp"
  }
}

Field	Description
`data.envelopeId`	ID of the sent envelope.
`data.name`	Display name of the envelope.

`envelope.finalized`

Fired when all required recipients have completed their actions and the envelope is fully signed.

{
  "event": "envelope.finalized",
  "data": {
    "envelopeId": "env_...",
    "context": { "contractId": "CNT-001" }
  }
}

Field	Description
`data.envelopeId`	ID of the finalized envelope.
`data.context`	The `context` object originally attached to the envelope.

`envelope.voided`

Fired when an envelope is manually voided via the API or customer panel.

{
  "event": "envelope.voided",
  "data": {
    "envelopeId": "env_...",
    "context": { "contractId": "CNT-001" }
  }
}

Field	Description
`data.envelopeId`	ID of the voided envelope.
`data.context`	The `context` object originally attached to the envelope.

`envelope.deleted`

Fired when an envelope is permanently deleted.

{
  "event": "envelope.deleted",
  "data": {
    "envelopeId": "env_...",
    "context": { "contractId": "CNT-001" }
  }
}

Field	Description
`data.envelopeId`	ID of the deleted envelope.
`data.context`	The `context` object originally attached to the envelope.

`document.finalized`

Fired when a single document within an envelope reaches a terminal status.

{
  "event": "document.finalized",
  "data": {
    "envelopeId": "env_...",
    "document": {
      "id": "doc_...",
      "name": "Service Agreement.pdf",
      "status": "completed",
      "context": {}
    }
  }
}

Field	Description
`data.envelopeId`	ID of the parent envelope.
`data.document.id`	ID of the document.
`data.document.name`	Display name of the document.
`data.document.status`	Terminal status: `completed`, `voided`, or `declined`.
`data.document.context`	The `context` object attached to the document.

`recipient.activated`

Fired when a recipient's signing turn begins — i.e. all preceding recipients (lower order values) have completed their actions.

{
  "event": "recipient.activated",
  "data": {
    "envelopeId": "env_...",
    "recipient": {
      "id": "rcp_...",
      "order": 1,
      "identifier": "counterparty",
      "agents": [
        {
          "id": "agt_...",
          "name": "Jane Smith",
          "email": "[email protected]",
          "phone": "+905001234567",
          "link": "https://next.inspakt.com/sign/...",
          "context": {}
        }
      ]
    }
  }
}

Field	Description
`data.envelopeId`	ID of the envelope.
`data.recipient.id`	ID of the activated recipient.
`data.recipient.identifier`	The identifier slug of the recipient role.
`data.recipient.order`	Signing order of this recipient.
`data.recipient.agents`	List of agents for this recipient. Each includes a `link` — the direct signing URL for that agent.

tip

Use the link field in recipient.activated to send a custom signing notification through your own communication channels instead of relying on Inspakt's default emails.

`recipient.completed-document`

Fired when a recipient completes (signs) a specific document.

{
  "event": "recipient.completed-document",
  "data": {
    "envelopeId": "env_...",
    "document": {
      "id": "doc_...",
      "name": "Service Agreement.pdf",
      "context": {}
    },
    "recipient": {
      "id": "rcp_...",
      "order": 0,
      "identifier": "counterparty",
      "agent": {
        "id": "agt_...",
        "name": "Jane Smith",
        "email": "[email protected]",
        "phone": "+905001234567",
        "context": {}
      }
    }
  }
}

Field	Description
`data.envelopeId`	ID of the envelope.
`data.document`	The document that was completed.
`data.recipient.agent`	The specific agent who completed the document.

`recipient.declined-document`

Fired when a recipient declines to sign a specific document.

{
  "event": "recipient.declined-document",
  "data": {
    "envelopeId": "env_...",
    "document": {
      "id": "doc_...",
      "name": "Service Agreement.pdf",
      "context": {}
    },
    "recipient": {
      "id": "rcp_...",
      "order": 0,
      "identifier": "counterparty",
      "agent": {
        "id": "agt_...",
        "name": "Jane Smith",
        "email": "[email protected]",
        "phone": "+905001234567",
        "context": {}
      }
    },
    "reason": "misleading_information",
    "explanation": "The contract terms do not match what was agreed verbally."
  }
}

Field	Description
`data.envelopeId`	ID of the envelope.
`data.document`	The document that was declined.
`data.recipient.agent`	The specific agent who declined.
`data.reason`	The declination reason selected by the recipient. See below.
`data.explanation`	Optional free-text explanation provided by the recipient.

Declination reasons

Value	Description
`wrong_person`	The recipient believes the document was sent to the wrong person.
`misleading_information`	The content of the document does not match the recipient's expectations.
`not_interested`	The recipient is not willing to proceed.
`other`	Another reason, usually accompanied by an `explanation`.

Endpoint requirements

Your webhook endpoint must:

Accept POST requests with Content-Type: application/json
Return any 2xx status code to acknowledge receipt
Respond within a reasonable timeout (recommend under 5 seconds)

Securing your endpoint

When registering a webhook in the customer panel, you can optionally provide a custom HTTP header (name and value) to include in every delivery. Use this to authenticate incoming requests on your end.

A common pattern is to add a secret token that your endpoint validates before processing:

Header name:  Authorization
Header value: Bearer my-secret-token

Your endpoint then rejects any request that does not include the expected header value.

tip

Choose a long, randomly generated value for the header. Treat it like a password — do not commit it to source control.

Quick event overview

Event	When it fires
`envelope.created`	Envelope is created
`envelope.sent`	Envelope is dispatched to recipients
`envelope.finalized`	All required recipients completed signing
`envelope.voided`	Envelope is manually cancelled
`envelope.deleted`	Envelope is permanently deleted
`document.finalized`	A document reaches a terminal status
`recipient.activated`	A recipient's signing turn begins
`recipient.completed-document`	A recipient signs a document
`recipient.declined-document`	A recipient declines a document

How it works​

Payload structure​

Event reference​

envelope.created​

envelope.sent​

envelope.finalized​

envelope.voided​

envelope.deleted​

document.finalized​

recipient.activated​

recipient.completed-document​

recipient.declined-document​

Endpoint requirements​

Securing your endpoint​

Quick event overview​