Leypal Corp Docs
Webhooks

Events

Complete reference of all 18 webhook event types from Leypal, with JSON examples and detailed flow descriptions for each event family.

Webhook Events Reference

Leypal sends webhook events for two event families: signature events (9 events) and identity verification events (9 events). Each webhook follows a standard wrapper structure, with event-specific fields within the data object.

This reference documents all 18 event types with complete JSON payload examples and explanations of the flows they follow. Use this page to build your event handler and understand exactly what data to expect at each stage of the process.

New to webhooks? Start with the Webhook Setup Guide to register your endpoint and understand how you'll receive these events.

Standard Payload Structure

Every webhook delivery — regardless of event type — includes the same top-level wrapper:

{
  "webhookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "event": "signature.created",
  "timestamp": "2026-03-31T14:23:01.000Z",
  "organizationId": 42,
  "data": {
    // event-specific fields
  }
}
FieldTypeRequiredDescription
webhookIdstring (UUID)YesUnique identifier for this specific delivery. Use it to deduplicate deliveries if Leypal retries.
eventstringYesEvent type name (e.g., signature.created). Use it to route to the correct handler.
timestampstring (ISO 8601)YesWhen the event occurred on Leypal servers, in UTC.
organizationIdnumberYesThe organization that owns the resource. Useful for multi-tenant setups.
dataobjectYesEvent-specific payload. Structure varies by event type.

Signature Events

Signature events track the complete lifecycle of a signature request, from initial creation through completion, including each step for each signer.

signature.created

Emitted when a new signature document is created.

{
  "webhookId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "event": "signature.created",
  "timestamp": "2026-03-31T14:23:01.000Z",
  "organizationId": 42,
  "data": {
    "signatureId": 1001,
    "status": "draft",
    "subject": "Service Agreement",
    "senderName": "Your Company",
    "type": "advanced",
    "signers": [
      {
        "id": 501,
        "email": "bob@example.com",
        "name": "Bob Builder",
        "status": "PENDING",
        "completedAt": null
      }
    ],
    "signerId": null,
    "signerEmail": null
  }
}

signature.signer_viewed

Emitted when a signer opens and views the document.

{
  "webhookId": "4ab96g75-6828-5673-c4gd-3d074g77bgb7",
  "event": "signature.signer_viewed",
  "timestamp": "2026-03-31T14:30:00.000Z",
  "organizationId": 42,
  "data": {
    "signatureId": 1001,
    "status": "created",
    "subject": "Service Agreement",
    "senderName": "Your Company",
    "type": "advanced",
    "signers": [
      {
        "id": 501,
        "email": "bob@example.com",
        "name": "Bob Builder",
        "status": "PENDING",
        "completedAt": null
      }
    ],
    "signerId": 501,
    "signerEmail": "bob@example.com"
  }
}

signature.signer_accepted_terms

Emitted when a signer accepts the terms and conditions.

{
  "webhookId": "5bc07h86-7939-6784-d5he-4e185h88chc8",
  "event": "signature.signer_accepted_terms",
  "timestamp": "2026-03-31T14:35:00.000Z",
  "organizationId": 42,
  "data": {
    "signatureId": 1001,
    "status": "created",
    "subject": "Service Agreement",
    "senderName": "Your Company",
    "type": "advanced",
    "signers": [
      {
        "id": 501,
        "email": "bob@example.com",
        "name": "Bob Builder",
        "status": "PENDING",
        "completedAt": null
      }
    ],
    "signerId": 501,
    "signerEmail": "bob@example.com"
  }
}

signature.signer_verified

Emitted when a signer's identity verification completes successfully.

{
  "webhookId": "6cd18i97-8a4a-7895-e6if-5f296i99did9",
  "event": "signature.signer_verified",
  "timestamp": "2026-03-31T14:40:00.000Z",
  "organizationId": 42,
  "data": {
    "signatureId": 1001,
    "status": "created",
    "subject": "Service Agreement",
    "senderName": "Your Company",
    "type": "advanced",
    "signers": [
      {
        "id": 501,
        "email": "bob@example.com",
        "name": "Bob Builder",
        "status": "PENDING",
        "completedAt": null
      }
    ],
    "signerId": 501,
    "signerEmail": "bob@example.com"
  }
}

signature.signer_signed

Emitted when a signer places their signature on the document. This event is emitted for each signer individually.

{
  "webhookId": "7de29j08-9b5b-8906-f7jg-6g3a7j00eje0",
  "event": "signature.signer_signed",
  "timestamp": "2026-03-31T14:45:00.000Z",
  "organizationId": 42,
  "data": {
    "signatureId": 1001,
    "status": "created",
    "subject": "Service Agreement",
    "senderName": "Your Company",
    "type": "advanced",
    "signers": [
      {
        "id": 501,
        "email": "bob@example.com",
        "name": "Bob Builder",
        "status": "PENDING",
        "completedAt": null
      }
    ],
    "signerId": 501,
    "signerEmail": "bob@example.com"
  }
}

signature.signed

Emitted when all signers have placed their signatures. At this point, the document is digitally signed and the evidence report is generated.

{
  "webhookId": "8ef30k19-acac-9017-g8kh-7h4b8k11fkf1",
  "event": "signature.signed",
  "timestamp": "2026-03-31T14:50:00.000Z",
  "organizationId": 42,
  "data": {
    "signatureId": 1001,
    "status": "created",
    "subject": "Service Agreement",
    "senderName": "Your Company",
    "type": "advanced",
    "signers": [
      {
        "id": 501,
        "email": "bob@example.com",
        "name": "Bob Builder",
        "status": "PENDING",
        "completedAt": "2026-03-31T14:45:00.000Z"
      }
    ],
    "signerId": null,
    "signerEmail": null
  }
}

signature.completed

Emitted when the signing process is completely finished — the document has been digitally signed, the evidence report is ready, and any identity verification has been completed.

{
  "webhookId": "9fg41l2a-bdbd-0128-h9li-8i5c9l22glg2",
  "event": "signature.completed",
  "timestamp": "2026-03-31T14:55:00.000Z",
  "organizationId": 42,
  "data": {
    "signatureId": 1001,
    "status": "completed",
    "subject": "Service Agreement",
    "senderName": "Your Company",
    "type": "advanced",
    "signers": [
      {
        "id": 501,
        "email": "bob@example.com",
        "name": "Bob Builder",
        "status": "PENDING",
        "completedAt": "2026-03-31T14:45:00.000Z"
      }
    ],
    "signerId": null,
    "signerEmail": null
  }
}

signature.reminder

Emitted when Leypal sends a reminder email to one or more signers who haven't yet signed.

{
  "webhookId": "0gh52m3b-ceec-1239-i0mj-9j6d0m33hmh3",
  "event": "signature.reminder",
  "timestamp": "2026-03-31T15:00:00.000Z",
  "organizationId": 42,
  "data": {
    "signatureId": 1001,
    "status": "created",
    "subject": "Service Agreement",
    "senderName": "Your Company",
    "type": "advanced",
    "signers": [
      {
        "id": 501,
        "email": "bob@example.com",
        "name": "Bob Builder",
        "status": "PENDING",
        "completedAt": null
      }
    ],
    "signerId": 501,
    "signerEmail": "bob@example.com"
  }
}

signature.rejected

Emitted when a signer explicitly declines to sign the request.

{
  "webhookId": "1hi63n4c-dfdf-2340-j1nk-0k7e1n44ini4",
  "event": "signature.rejected",
  "timestamp": "2026-03-31T15:05:00.000Z",
  "organizationId": 42,
  "data": {
    "signatureId": 1001,
    "status": "rejected",
    "subject": "Service Agreement",
    "senderName": "Your Company",
    "type": "advanced",
    "signers": [
      {
        "id": 501,
        "email": "bob@example.com",
        "name": "Bob Builder",
        "status": "PENDING",
        "completedAt": null
      }
    ],
    "signerId": 501,
    "signerEmail": "bob@example.com"
  }
}

Identity Verification Events

Identity verification events track each stage of the verification process, from session creation through completion of automated analysis.

identity_verification.created

Emitted when a new identity verification is created.

{
  "webhookId": "2ij74o5d-egeg-3451-k2ol-1l8f2o55joj5",
  "event": "identity_verification.created",
  "timestamp": "2026-03-31T14:23:01.000Z",
  "organizationId": 42,
  "data": {
    "id": 52,
    "status": "pending",
    "email": "juan@example.com",
    "name": "Juan Perez",
    "contactId": null,
    "approvedAt": null,
    "attemptsUsed": 0,
    "maxAttempts": 3,
    "expiresAt": "2026-04-07T14:34:53.337Z",
    "session": null
  }
}

identity_verification.session_started

Emitted when the user begins the verification session.

{
  "webhookId": "3jk85p6e-fhfh-4562-l3pm-2m9g3p66kpk6",
  "event": "identity_verification.session_started",
  "timestamp": "2026-03-31T14:30:00.000Z",
  "organizationId": 42,
  "data": {
    "id": 52,
    "status": "pending",
    "email": "juan@example.com",
    "name": "Juan Perez",
    "contactId": null,
    "approvedAt": null,
    "attemptsUsed": 1,
    "maxAttempts": 3,
    "expiresAt": "2026-04-07T14:34:53.337Z",
    "session": {
      "id": "abc-123-def",
      "status": "IN_PROGRESS",
      "attemptNumber": 1,
      "startedAt": "2026-03-31T14:30:00.000Z",
      "completedAt": null,
      "livenessPassed": null,
      "faceMatchPassed": null,
      "faceMatchScore": null,
      "idVerificationPassed": null,
      "documentClassification": null,
      "failureReason": null
    }
  }
}

identity_verification.document_front_uploaded

Emitted when the user uploads the front of their ID document.

{
  "webhookId": "4kl96q7f-ghgh-5673-m4qn-3n0h4q77lql7",
  "event": "identity_verification.document_front_uploaded",
  "timestamp": "2026-03-31T14:40:00.000Z",
  "organizationId": 42,
  "data": {
    "id": 52,
    "status": "pending",
    "email": "juan@example.com",
    "name": "Juan Perez",
    "contactId": null,
    "approvedAt": null,
    "attemptsUsed": 1,
    "maxAttempts": 3,
    "expiresAt": "2026-04-07T14:34:53.337Z",
    "session": {
      "id": "abc-123-def",
      "status": "IN_PROGRESS",
      "attemptNumber": 1,
      "startedAt": "2026-03-31T14:30:00.000Z",
      "completedAt": null,
      "livenessPassed": null,
      "faceMatchPassed": null,
      "faceMatchScore": null,
      "idVerificationPassed": null,
      "documentClassification": null,
      "failureReason": null
    }
  }
}

identity_verification.document_back_uploaded

Emitted when the user uploads the back of their ID document.

{
  "webhookId": "5lm07r8g-hihi-6784-n5ro-4o1i5r88mrl8",
  "event": "identity_verification.document_back_uploaded",
  "timestamp": "2026-03-31T14:45:00.000Z",
  "organizationId": 42,
  "data": {
    "id": 52,
    "status": "pending",
    "email": "juan@example.com",
    "name": "Juan Perez",
    "contactId": null,
    "approvedAt": null,
    "attemptsUsed": 1,
    "maxAttempts": 3,
    "expiresAt": "2026-04-07T14:34:53.337Z",
    "session": {
      "id": "abc-123-def",
      "status": "IN_PROGRESS",
      "attemptNumber": 1,
      "startedAt": "2026-03-31T14:30:00.000Z",
      "completedAt": null,
      "livenessPassed": null,
      "faceMatchPassed": null,
      "faceMatchScore": null,
      "idVerificationPassed": null,
      "documentClassification": null,
      "failureReason": null
    }
  }
}

identity_verification.liveness_started

Emitted when the liveness verification (selfie) begins.

{
  "webhookId": "6mn18s9h-ijij-7895-o6sp-5p2j6s99nsn9",
  "event": "identity_verification.liveness_started",
  "timestamp": "2026-03-31T14:50:00.000Z",
  "organizationId": 42,
  "data": {
    "id": 52,
    "status": "pending",
    "email": "juan@example.com",
    "name": "Juan Perez",
    "contactId": null,
    "approvedAt": null,
    "attemptsUsed": 1,
    "maxAttempts": 3,
    "expiresAt": "2026-04-07T14:34:53.337Z",
    "session": {
      "id": "abc-123-def",
      "status": "IN_PROGRESS",
      "attemptNumber": 1,
      "startedAt": "2026-03-31T14:30:00.000Z",
      "completedAt": null,
      "livenessPassed": null,
      "faceMatchPassed": null,
      "faceMatchScore": null,
      "idVerificationPassed": null,
      "documentClassification": null,
      "failureReason": null
    }
  }
}

identity_verification.liveness_end

Emitted when the liveness verification completes.

{
  "webhookId": "7no29t0i-jkjk-8906-p7tq-6q3k7t00oto0",
  "event": "identity_verification.liveness_end",
  "timestamp": "2026-03-31T14:55:00.000Z",
  "organizationId": 42,
  "data": {
    "id": 52,
    "status": "pending",
    "email": "juan@example.com",
    "name": "Juan Perez",
    "contactId": null,
    "approvedAt": null,
    "attemptsUsed": 1,
    "maxAttempts": 3,
    "expiresAt": "2026-04-07T14:34:53.337Z",
    "session": {
      "id": "abc-123-def",
      "status": "IN_PROGRESS",
      "attemptNumber": 1,
      "startedAt": "2026-03-31T14:30:00.000Z",
      "completedAt": null,
      "livenessPassed": true,
      "faceMatchPassed": null,
      "faceMatchScore": null,
      "idVerificationPassed": null,
      "documentClassification": null,
      "failureReason": null
    }
  }
}

identity_verification.ml_pipeline_completed

Emitted when the automated verification pipeline (document analysis and face matching) completes successfully.

{
  "webhookId": "8op3a0u1-klkl-9017-q8ur-7r4l8u11pup1",
  "event": "identity_verification.ml_pipeline_completed",
  "timestamp": "2026-03-31T15:10:00.000Z",
  "organizationId": 42,
  "data": {
    "id": 52,
    "status": "approved",
    "email": "juan@example.com",
    "name": "Juan Perez",
    "contactId": null,
    "approvedAt": "2026-03-31T15:10:00.000Z",
    "attemptsUsed": 1,
    "maxAttempts": 3,
    "expiresAt": "2026-04-07T14:34:53.337Z",
    "session": {
      "id": "abc-123-def",
      "status": "SUCCESS",
      "attemptNumber": 1,
      "startedAt": "2026-03-31T14:30:00.000Z",
      "completedAt": "2026-03-31T15:10:00.000Z",
      "livenessPassed": true,
      "faceMatchPassed": true,
      "faceMatchScore": 98.5,
      "idVerificationPassed": true,
      "documentClassification": "PASSPORT",
      "failureReason": null
    }
  }
}

identity_verification.ml_pipeline_failed

Emitted when the automated verification pipeline fails — this can be due to invalid documents, insufficient quality, or a technical issue.

{
  "webhookId": "9pq4b1v2-lmlm-0128-r9vs-8s5m9v22qvq2",
  "event": "identity_verification.ml_pipeline_failed",
  "timestamp": "2026-03-31T15:10:00.000Z",
  "organizationId": 42,
  "data": {
    "id": 52,
    "status": "rejected",
    "email": "juan@example.com",
    "name": "Juan Perez",
    "contactId": null,
    "approvedAt": null,
    "attemptsUsed": 1,
    "maxAttempts": 3,
    "expiresAt": "2026-04-07T14:34:53.337Z",
    "session": {
      "id": "abc-123-def",
      "status": "FAILED",
      "attemptNumber": 1,
      "startedAt": "2026-03-31T14:30:00.000Z",
      "completedAt": "2026-03-31T15:10:00.000Z",
      "livenessPassed": false,
      "faceMatchPassed": null,
      "faceMatchScore": null,
      "idVerificationPassed": false,
      "documentClassification": "UNCERTAIN",
      "failureReason": "Document quality insufficient"
    }
  }
}

identity_verification.review_requested

Emitted when the automated pipeline determines that the case requires manual review by an operator.

{
  "webhookId": "0qr5c2w3-mnmn-1239-s0wt-9t6n0w33rwt3",
  "event": "identity_verification.review_requested",
  "timestamp": "2026-03-31T15:10:00.000Z",
  "organizationId": 42,
  "data": {
    "id": 52,
    "status": "pending_review",
    "email": "juan@example.com",
    "name": "Juan Perez",
    "contactId": null,
    "approvedAt": null,
    "attemptsUsed": 1,
    "maxAttempts": 3,
    "expiresAt": "2026-04-07T14:34:53.337Z",
    "session": {
      "id": "abc-123-def",
      "status": "UNDER_REVIEW",
      "attemptNumber": 1,
      "startedAt": "2026-03-31T14:30:00.000Z",
      "completedAt": "2026-03-31T15:10:00.000Z",
      "livenessPassed": true,
      "faceMatchPassed": true,
      "faceMatchScore": 87.5,
      "idVerificationPassed": true,
      "documentClassification": "PASSPORT",
      "failureReason": null
    }
  }
}

Event Flows

Typical Signature Flow

  1. signature.created — Signature created
  2. signature.signer_viewed — Signer opens the document (for each signer)
  3. signature.signer_accepted_terms — Signer accepts terms (for each signer)
  4. signature.signer_verified — Identity verification completed (if required, for each signer)
  5. signature.signer_signed — Signer places signature (for each signer)
  6. signature.signed — All signers have signed, document is digitally signed
  7. signature.completed — Signature process completely finished

Typical Identity Verification Flow

  1. identity_verification.created — Verification initiated
  2. identity_verification.session_started — User begins the process
  3. identity_verification.document_front_uploaded — User uploads document front
  4. identity_verification.document_back_uploaded — User uploads document back
  5. identity_verification.liveness_started — Liveness verification begins
  6. identity_verification.liveness_end — Liveness verification completes
  7. identity_verification.ml_pipeline_completed or ml_pipeline_failed or review_requested — Final analysis result

Next Steps

Setup Guide

Register your webhook endpoint, receive all events automatically, and understand HTTP response codes and retry behavior.

Errors & Troubleshooting

Complete reference for webhook HTTP response codes, retry behavior, signature verification errors, and a step-by-step troubleshooting flowchart.

On this page

Webhook Events ReferenceStandard Payload StructureSignature Eventssignature.createdsignature.signer_viewedsignature.signer_accepted_termssignature.signer_verifiedsignature.signer_signedsignature.signedsignature.completedsignature.remindersignature.rejectedIdentity Verification Eventsidentity_verification.createdidentity_verification.session_startedidentity_verification.document_front_uploadedidentity_verification.document_back_uploadedidentity_verification.liveness_startedidentity_verification.liveness_endidentity_verification.ml_pipeline_completedidentity_verification.ml_pipeline_failedidentity_verification.review_requestedEvent FlowsTypical Signature FlowTypical Identity Verification FlowNext Steps