Skip to main content

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​

EventFires on
envelope.createdA new envelope record was created.
envelope.sentThe envelope was sent to its signers.
envelope.viewedThe first signer opened the document (fires once, on sent -> viewed).
envelope.completed ⚠️All parties signed. Carries the filled-in field values.
envelope.declinedA signer declined to sign.
envelope.voidedThe envelope was voided before completion.
envelope.recalledThe sender recalled the envelope. Also fires envelope.voided with recalled:true for one release.
envelope.expiredThe envelope passed its expiry date without completing.
envelope.reminder_sentA signing reminder was emailed.
envelope.deletedThe envelope was soft-deleted.

Signer lifecycle​

EventFires on
signer.viewedA signer opened the document (fires on every view).
signer.startedA signer began filling the document.
signer.completedOne signer finished; others may remain.
signer.declinedA specific signer declined.

Vault & compliance​

EventFires on
vault.storedThe authoritative copy was stored and hashed.
vault.compliance.passedUCC 9-105 evaluation scored 100.
vault.compliance.failedUCC 9-105 evaluation scored below 100.
vault.releasedVault-out: the authoritative copy was irreversibly released.
vault.document.accessedA vaulted document was downloaded.
vault.document.tamper_detectedA stored document failed hash re-verification.
vault.integrity.verifiedThe scheduled integrity sweep re-verified the document hash.

Custody​

EventFires on
custodian.transferA custody transfer was requested and is pending acceptance.
custodian.acceptedThe target custodian accepted custody.
custodian.rejectedThe target custodian rejected custody.
custodian.revokedAn existing custodian permission was revoked.

Customers​

EventFires 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​

EventFires on
invoice.createdAn invoice was created on the org billing rail.
invoice.paidAn invoice was paid in full.
invoice.payment_failedA payment attempt on the invoice failed.
invoice.voidedAn invoice was voided.
invoice.reminder_sentA payment reminder was emailed.

Subscriptions​

EventFires on
subscription.createdA recurring subscription was provisioned.
subscription.cancelledA recurring subscription was cancelled.

Proposals​

EventFires on
proposal.sentA proposal was sent to the customer.
proposal.acceptedThe customer accepted the proposal.
proposal.declinedThe customer declined the proposal.

Webhook meta​

EventFires on
webhook.testFired 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": "buyer@example.com", "name": "Ada Lovelace", "role": "Buyer", "completed_at": "2026-08-27T15:03:58.000Z" }
    ],
    "fields": [
      { "name": "Monthly Rate", "type": "number", "value": 49.99, "signer_email": "buyer@example.com", "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": "buyer@example.com",
    "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": "buyer@example.com"
  }
}

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​