Webhook events

Every event below can be subscribed to individually, by domain wildcard (envelope.*), or all at once (*). See Managing endpoints for how selectors work.

Events marked ⚠️ can carry personal data — names, email addresses, or the values typed into a signed document. Subscribe to those deliberately.

Document lifecycle

Event	Fires on
`envelope.created`	A new envelope record was created.
`envelope.sent`	The envelope was sent to its signers.
`envelope.viewed`	The first signer opened the document (fires once, on sent -> viewed).
`envelope.completed` ⚠️	All parties signed. Carries the filled-in field values.
`envelope.declined`	A signer declined to sign.
`envelope.voided`	The envelope was voided before completion.
`envelope.recalled`	The sender recalled the envelope. Also fires envelope.voided with recalled:true for one release.
`envelope.expired`	The envelope passed its expiry date without completing.
`envelope.reminder_sent`	A signing reminder was emailed.
`envelope.deleted`	The envelope was soft-deleted.

Signer lifecycle

Event	Fires on
`signer.viewed`	A signer opened the document (fires on every view).
`signer.started`	A signer began filling the document.
`signer.completed`	One signer finished; others may remain.
`signer.declined`	A specific signer declined.

Vault & compliance

Event	Fires on
`vault.stored`	The authoritative copy was stored and hashed.
`vault.compliance.passed`	UCC 9-105 evaluation scored 100.
`vault.compliance.failed`	UCC 9-105 evaluation scored below 100.
`vault.released`	Vault-out: the authoritative copy was irreversibly released.
`vault.document.accessed`	A vaulted document was downloaded.
`vault.document.tamper_detected`	A stored document failed hash re-verification.
`vault.integrity.verified`	The scheduled integrity sweep re-verified the document hash.

Custody

Event	Fires on
`custodian.transfer`	A custody transfer was requested and is pending acceptance.
`custodian.accepted`	The target custodian accepted custody.
`custodian.rejected`	The target custodian rejected custody.
`custodian.revoked`	An existing custodian permission was revoked.

Customers

Event	Fires on
`customer.created` ⚠️	A customer record was created.
`customer.updated` ⚠️	A customer record changed. Carries changed keys, not the full record.
`customer.archived` ⚠️	A customer was archived.
`customer.restored` ⚠️	An archived customer was restored.
`customer.deleted` ⚠️	A customer record was deleted.

Invoices

Event	Fires on
`invoice.created`	An invoice was created on the org billing rail.
`invoice.paid`	An invoice was paid in full.
`invoice.payment_failed`	A payment attempt on the invoice failed.
`invoice.voided`	An invoice was voided.
`invoice.reminder_sent`	A payment reminder was emailed.

Subscriptions

Event	Fires on
`subscription.created`	A recurring subscription was provisioned.
`subscription.cancelled`	A recurring subscription was cancelled.

Proposals

Event	Fires on
`proposal.sent`	A proposal was sent to the customer.
`proposal.accepted`	The customer accepted the proposal.
`proposal.declined`	The customer declined the proposal.

Webhook meta

Event	Fires on
`webhook.test`	Fired by the "Send test" action on an endpoint.

Envelope payloads

envelope.created

{
  "event_type": "envelope.created",
  "event_id": "evt_1a2b3c4d5e6f7a8b9c0d1e2f",
  "org_id": "org_abc123",
  "envelope_id": "env_x7k9m2p4q1w3",
  "timestamp": "2026-08-27T09:50:00.000Z",
  "data": { "envelope_id": "env_x7k9m2p4q1w3", "customer_id": "cust_abc123" }
}

envelope.sent

{
  "event_type": "envelope.sent",
  "event_id": "evt_2b3c4d5e6f7a8b9c0d1e2f3a",
  "org_id": "org_abc123",
  "envelope_id": "env_x7k9m2p4q1w3",
  "timestamp": "2026-08-27T10:00:00.000Z",
  "data": {
    "envelope_id": "env_x7k9m2p4q1w3",
    "sent_at": "2026-08-27T10:00:00.000Z",
    "submission_id": "sub_123"
  }
}

envelope.completed ⚠️

The headline event: fired once every party has signed, carrying the values filled into the document. The data.fields contract is documented in full on Signed document field data.

{
  "event_type": "envelope.completed",
  "event_id": "evt_9f3a2b1c4d5e6f7a8b9c0d1e",
  "org_id": "org_abc123",
  "envelope_id": "env_x7k9m2p4q1w3",
  "timestamp": "2026-08-27T15:04:05.000Z",
  "data": {
    "envelope_id": "env_x7k9m2p4q1w3",
    "envelope_name": "Monitoring Agreement",
    "customer_id": "cust_abc123",
    "completed_at": "2026-08-27T15:04:05.000Z",
    "docuseal_submission_id": "1234",
    "signers": [
      { "email": "[email protected]", "name": "Ada Lovelace", "role": "Buyer", "completed_at": "2026-08-27T15:03:58.000Z" }
    ],
    "fields": [
      { "name": "Monthly Rate", "type": "number", "value": 49.99, "signer_email": "[email protected]", "signer_role": "Buyer", "field_id": null, "submitter_uuid": "8f14e45f-..." }
    ],
    "fields_truncated": false
  }
}

envelope.declined

{
  "event_type": "envelope.declined",
  "event_id": "evt_4d5e6f7a8b9c0d1e2f3a4b5c",
  "org_id": "org_abc123",
  "envelope_id": "env_x7k9m2p4q1w3",
  "timestamp": "2026-08-27T11:30:00.000Z",
  "data": {
    "envelope_id": "env_x7k9m2p4q1w3",
    "signer": "Ada Lovelace",
    "signer_email": "[email protected]",
    "decline_reason": "Pricing needs review"
  }
}

envelope.voided and envelope.recalled

A void cancels an envelope outright. A recall pulls back an envelope that was already sent.

Deprecation in progress

Recall historically fired envelope.voided with "recalled": true. It now fires both envelope.voided (with that flag, unchanged) and the new envelope.recalled. The duplicate envelope.voided will be removed in a future release — migrate any recall handling to envelope.recalled, and deduplicate on event_id in the meantime.

{
  "event_type": "envelope.recalled",
  "event_id": "evt_3c4d5e6f7a8b9c0d1e2f3a4b",
  "org_id": "org_abc123",
  "envelope_id": "env_x7k9m2p4q1w3",
  "timestamp": "2026-08-27T11:00:00.000Z",
  "data": { "envelope_id": "env_x7k9m2p4q1w3", "previous_status": "sent" }
}

Signer payloads

signer.* events are per participant; envelope.* are the document-level rollups. On a two-signer document you receive two signer.completed events and then one envelope.completed.

envelope.viewed fires once, on the real sent → viewed transition. signer.viewed fires on every view, including repeats by the same person.

{
  "event_type": "signer.completed",
  "event_id": "evt_5e6f7a8b9c0d1e2f3a4b5c6d",
  "org_id": "org_abc123",
  "envelope_id": "env_x7k9m2p4q1w3",
  "timestamp": "2026-08-27T14:12:00.000Z",
  "data": {
    "envelope_id": "env_x7k9m2p4q1w3",
    "signer": "Ada Lovelace",
    "signer_email": "[email protected]"
  }
}

Vault payloads

vault.stored

{
  "event_type": "vault.stored",
  "event_id": "evt_6f7a8b9c0d1e2f3a4b5c6d7e",
  "org_id": "org_abc123",
  "envelope_id": "env_x7k9m2p4q1w3",
  "timestamp": "2026-08-27T15:10:00.000Z",
  "data": {
    "path": "ucc-vault/org_abc123/env_x7k9m2p4q1w3/signed.pdf",
    "hash": "a1b2c3d4...",
    "source": "esign"
  }
}

vault.released

Vault-out. The authoritative copy has been irreversibly released — the most consequential event in the vault lifecycle.

{
  "event_type": "vault.released",
  "event_id": "evt_7a8b9c0d1e2f3a4b5c6d7e8f",
  "org_id": "org_abc123",
  "envelope_id": "env_x7k9m2p4q1w3",
  "timestamp": "2026-08-27T16:00:00.000Z",
  "data": {
    "envelope_id": "env_x7k9m2p4q1w3",
    "customer_id": "cust_abc123",
    "released_by_user_id": "usr_abc123",
    "released_at": "2026-08-27T16:00:00.000Z"
  }
}

vault.document.tamper_detected

The daily integrity sweep re-downloads each vaulted object, re-hashes it, and compares against the stored hash. A mismatch fires this event and vault.compliance.failed, so subscribers written against the older behaviour keep working.

{
  "event_type": "vault.document.tamper_detected",
  "event_id": "evt_8b9c0d1e2f3a4b5c6d7e8f9a",
  "org_id": "org_abc123",
  "envelope_id": "env_x7k9m2p4q1w3",
  "timestamp": "2026-08-27T04:00:00.000Z",
  "data": {
    "envelope_id": "env_x7k9m2p4q1w3",
    "reason": "integrity_check_failed",
    "stored_hash": "a1b2c3d4...",
    "computed_hash": "9f8e7d6c...",
    "compliance_score": 85,
    "check_id": "ichk_abc123"
  }
}

Customer payloads

Customer events carry identifiers and changed keys — never the full record. customer.updated tells you what changed so you can re-fetch; it does not push addresses or contact details to your endpoint.

{
  "event_type": "customer.updated",
  "event_id": "evt_9c0d1e2f3a4b5c6d7e8f9a0b",
  "org_id": "org_abc123",
  "envelope_id": null,
  "timestamp": "2026-08-27T12:00:00.000Z",
  "data": { "customer_id": "cust_abc123", "changed_keys": ["phone", "address_line1"] }
}

webhook.test

Fired by the Send test action on an endpoint. envelope_id is null.

{
  "event_type": "webhook.test",
  "event_id": "evt_test_1a2b3c4d5e6f7a8b",
  "org_id": "org_abc123",
  "envelope_id": null,
  "timestamp": "2026-08-27T10:00:00.000Z",
  "data": { "message": "This is a test delivery from Loyva. Your endpoint is configured correctly." }
}

Next steps

Managing endpoints — subscribing to these events
Signed document field data — the envelope.completed payload
Verification — verifying signatures

Document lifecycle​

Signer lifecycle​

Vault & compliance​

Custody​

Customers​

Invoices​

Subscriptions​

Proposals​

Webhook meta​

Envelope payloads​

envelope.created​

envelope.sent​

envelope.completed ⚠️​

envelope.declined​

envelope.voided and envelope.recalled​

Signer payloads​

Vault payloads​

vault.stored​

vault.released​

vault.document.tamper_detected​

Customer payloads​

webhook.test​

Next steps​