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 — manually, or automatically by Loyva's reminder schedule. data.trigger is manual or automatic.
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. The same fields, plus the envelope's contract terms, can be read back any time from GET /partner/envelopes/:id.

{
  "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​