Webhook Events

The table below documents every event type, and marks which are currently dispatched by the platform vs. reserved for future or internal use.

Event	Status	Fires on
envelope.created	Dispatched	New envelope created
envelope.sent	Dispatched	Envelope sent to signers
envelope.voided	Dispatched	Envelope voided
envelope.reminder_sent	Dispatched	Signing reminder sent (via API or internal)
vault.stored	Dispatched	Signed PDF stored in the vault with hash
vault.compliance.passed	Dispatched	UCC evaluation scored 100
vault.compliance.failed	Dispatched	UCC evaluation scored < 100
custodian.transfer	Dispatched	Custody transfer initiated
webhook.test	Dispatched	Triggered via POST /partners/keys/:key_id/test-webhook
envelope.viewed	Reserved	Constant defined, not currently fired
envelope.completed	Reserved	Constant defined, not currently fired — completion is observable via vault.stored
envelope.declined	Reserved	Constant defined, not currently fired
envelope.expired	Reserved	Constant defined, not currently fired
vault.document.accessed	Reserved	Constant defined, not currently fired
vault.document.tamper_detected	Reserved	Constant defined, not currently fired
custodian.accepted	Reserved	Constant defined, not currently fired
custodian.rejected	Reserved	Constant defined, not currently fired

note

Subscribe to the events you need, but do not require reserved events for critical flows — they may or may not be emitted depending on platform version.

Envelope events

envelope.created

{
  "event_type": "envelope.created",
  "event_id": "evt_1a2b3c4d5e6f7a8b9c0d1e2f",
  "org_id": "org_abc123",
  "envelope_id": "env_x7k9m2p4q1w3",
  "timestamp": "2026-04-11T09: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-04-11T10:00:00.000Z",
  "data": {
    "envelope_id": "env_x7k9m2p4q1w3",
    "sent_at": "2026-04-11T10:00:00.000Z",
    "submission_id": "sub_123"
  }
}

envelope.voided

{
  "event_type": "envelope.voided",
  "event_id": "evt_3c4d5e6f7a8b9c0d1e2f3a4b",
  "org_id": "org_abc123",
  "envelope_id": "env_x7k9m2p4q1w3",
  "timestamp": "2026-04-11T11:00:00.000Z",
  "data": {
    "envelope_id": "env_x7k9m2p4q1w3",
    "reason": "Customer withdrew"
  }
}

envelope.reminder_sent

Fired whenever a signing reminder is dispatched — either via POST /partner/envelopes/:id/remind or the internal remind endpoint.

{
  "event_type": "envelope.reminder_sent",
  "event_id": "evt_4a5b6c7d8e9f0a1b2c3d4e5f",
  "org_id": "org_abc123",
  "envelope_id": "env_x7k9m2p4q1w3",
  "timestamp": "2026-04-11T11:30:00.000Z",
  "data": {
    "envelope_id": "env_x7k9m2p4q1w3",
    "reminded": ["[email protected]", "[email protected]"]
  }
}

Vault events

vault.stored

{
  "event_type": "vault.stored",
  "event_id": "evt_4d5e6f7a8b9c0d1e2f3a4b5c",
  "org_id": "org_abc123",
  "envelope_id": "env_x7k9m2p4q1w3",
  "timestamp": "2026-04-11T10:16:00.000Z",
  "data": {
    "path": "ucc-vault/org_abc123/env_x7k9m2p4q1w3/signed.pdf",
    "hash": "a1b2c3d4e5f6..."
  }
}

info

For paper and electronic vault-in flows, data also includes source: "paper_upload" or source: "electronic_signed".

vault.compliance.passed

{
  "event_type": "vault.compliance.passed",
  "event_id": "evt_5e6f7a8b9c0d1e2f3a4b5c6d",
  "org_id": "org_abc123",
  "envelope_id": "env_x7k9m2p4q1w3",
  "timestamp": "2026-04-11T10:16:05.000Z",
  "data": {
    "score": 100,
    "certificate_path": "ucc-vault/org_abc123/env_x7k9m2p4q1w3/certificate.json"
  }
}

vault.compliance.failed

{
  "event_type": "vault.compliance.failed",
  "event_id": "evt_6f7a8b9c0d1e2f3a4b5c6d7e",
  "org_id": "org_abc123",
  "envelope_id": "env_x7k9m2p4q1w3",
  "timestamp": "2026-04-11T10:16:05.000Z",
  "data": {
    "score": 88,
    "missing_requirements": [
      "Secured party / assignee must be identified on the authoritative copy (secured_party field)"
    ],
    "certificate_path": "ucc-vault/org_abc123/env_x7k9m2p4q1w3/certificate.json"
  }
}

Custodian events

custodian.transfer

{
  "event_type": "custodian.transfer",
  "event_id": "evt_7a8b9c0d1e2f3a4b5c6d7e8f",
  "org_id": "org_abc123",
  "envelope_id": "env_x7k9m2p4q1w3",
  "timestamp": "2026-04-11T14:00:00.000Z",
  "data": {
    "envelope_id": "env_x7k9m2p4q1w3",
    "from_user_id": "usr_alice",
    "to_user_id": "usr_bank",
    "permission_id": "cp_abc123"
  }
}

Utility events

webhook.test

Dispatched when Loyva fires a one-off test delivery against your configured webhook URL. Useful for verifying connectivity and signature verification end-to-end.

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