Skip to main content
Webhooks let your application react to events in Lumin as they happen. Instead of repeatedly calling the API to check for changes, Lumin sends an HTTP POST request to your endpoint with a JSON payload describing the event. Common use cases include:
  • Downloading signed documents as soon as all parties complete signing
  • Keeping external systems like CRMs or ERPs in sync with signing status
  • Notifying your team when a document is declined or cancelled
  • Triggering internal workflows after a signature request is approved

​
How webhooks work

When an event occurs in Lumin, the following sequence happens:
1

Event is triggered

A user or API action causes an event — for example, all signers complete a document.
2

Lumin sends a notification

Lumin POSTs a JSON payload to your registered webhook URL describing the event.
3

Your server acknowledges

Your endpoint returns HTTP 200 OK to confirm receipt. No response body is required.
4

Your logic runs

Your application processes the event — for example, calls GET /v1/signature_request/{id}/file to download the signed PDF.

​
Example workflow

A user sends a signature request in Lumin Sign. Once all signers complete it:
  1. Lumin sends a signature_request_approved event to your endpoint.
  2. Your server returns 200 OK.
  3. Your app calls GET https://api.luminpdf.com/v1/signature_request/{id}/file to download the Certificate of Completion and signed PDF.

​
Types of webhooks

Lumin supports two webhook types, scoped differently:
TypeScopeConfiguration
Account webhooksAll events across your entire workspaceSettings → Developer settings → API Key → Account callback
App webhooksEvents limited to OAuth scopes granted by usersSettings → Developer settings → Integration apps → App webhook
  • Account webhooks — Configure once and receive all supported events workspace-wide.
  • App webhooks — Scoped to the permissions your OAuth app has been granted.

​
Supported event types

EventDescription
signature_request_createdA signature request was created successfully
signature_request_viewedA signer opened the document
signature_request_signedA signer signed the document
signature_request_approvedAll signers have completed signing
signature_request_declinedA signer declined — the request status changes to REJECTED
signature_request_downloadableThe signed document and/or Certificate of Completion is ready for download
signature_request_invalidAn error occurred while processing the request (e.g. invalid text tags)
signature_request_canceledThe signature request was cancelled
signature_request_cancel_failedThe cancellation attempt failed
signature_request_due_date_updatedThe due date on the signature request was updated

​
Event payload structure

All webhook events share the same JSON structure: 
{
  "event": {
    "event_time": 1758812586180,
    "event_type": "signature_request_downloadable",
    "event_metadata": {
      "workspace_id": "68d417dcdeaecfae84872de8"
    }
  },
  "signature_request": {
    "signature_request_id": "68d558daa153cb3c30718518",
    "title": "Test webhook",
    "created_at": 1758812378277,
    "updated_at": 1758812574883,
    "expires_at": 1827510980694,
    "status": "APPROVED",
    "signers": [
      {
        "name": "John Doe",
        "email": "[email protected]",
        "status": "APPROVED",
        "is_approved": true
      }
    ]
  },
  "details_url": "https://sign.luminpdf.com/auth?mode=view-contract&token=..."
}

​
Retry schedule

If your endpoint does not return 200 OK, Lumin retries delivery up to six times:
Retry attemptDelay after previous attempt
First5 minutes
Second15 minutes
Third45 minutes
Fourth2 hours 15 minutes
Fifth6 hours 45 minutes
Sixth20 hours 15 minutes

​
Failure conditions

A delivery attempt is considered failed when:
  • Timeout — your endpoint does not respond within 30 seconds
  • Non-200 response — your endpoint returns any HTTP status other than 200
  • Connection failure — Lumin cannot connect to your endpoint

​
Best practices

Respond immediately, process asynchronously. Return 200 OK as quickly as possible, then handle the event in a background job. This keeps your response time well under the 30-second timeout.
  • Implement idempotency — Lumin may deliver the same event more than once due to retries. Use signature_request_id and event_type together as a unique key to detect and ignore duplicates.
  • Verify signatures — Every request includes an X-Signature header. Always validate it before processing the payload. See Account webhooks and App webhooks for verification details.
  • Log all events — Store raw payloads for debugging and audit purposes.
  • Use HTTPS — Lumin only delivers webhooks to HTTPS endpoints.