Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.luminpdf.com/llms.txt

Use this file to discover all available pages before exploring further.

An app webhook is tied to a specific OAuth 2.0 application. Lumin delivers events only for users who have authorized your app, and only for the event types covered by the OAuth scopes they granted.
Only the Workspace Owner can configure or update the app webhook URL. App webhooks are only available for Private (Server) application types.

​
How app webhooks differ from account webhooks

Account webhooksApp webhooks
ScopeAll events, all users in the workspaceEvents from users who authorized your app
FilteringNone — you receive everythingLimited to the OAuth scopes the user granted
Signing secretPrimary API keyApp signing secret
Use caseInternal integrations, workspace monitoringThird-party OAuth integrations

​
Configure an app webhook

1

Open Developer settings

In Lumin, go to Settings → Developer settings → Integration apps tab.
2

Select your app

Click the app you want to configure. If you haven’t created one yet, click Create app.
3

Enter your webhook URL

Under the Receive events on behalf of users section, enter your endpoint URL. The URL must use HTTPS.
4

Save

Click Save.

​
Events received

Your app webhook receives events based on the OAuth scopes users have granted your app. For example, if a user does not grant the sign:requests.read or sign:requests scope, your app will not receive signature request events for that user. For the full list of available event types, see Supported event types.
Delivery behaviorDetail
One request per eventEach event triggers a separate HTTP POST
Real-time deliveryEvents are sent as they occur
User-scoped coverageOnly events from users who authorized your app
Scope-dependent filteringEvents limited to the OAuth scopes the user granted

​
Verify webhook signatures

Every request Lumin sends includes the following headers:
  • User-Agent: Always Lumin Sign API
  • X-Signature: An HMAC-SHA256 hex digest of the request body, signed with your app’s signing secret
Always verify the X-Signature header before processing a webhook payload. Reject any request where the signature does not match.
Your app’s signing secret is available in Settings → Developer settings → Integration apps → Application details. To verify a signature:
1

Read the header

Extract the X-Signature value from the incoming request headers.
2

Compute the expected signature

Compute HMAC-SHA256 of the raw request body using your app’s signing secret.
3

Compare

Compare your computed value to the X-Signature header. Use a constant-time comparison to avoid timing attacks.
4

Reject mismatches

If the values do not match, reject the request with a non-200 status.
Example using OpenSSL: 
signing_secret='your_app_signing_secret'
json='{"event":{"event_time":1694664207595,"event_type":"signature_request_sent"},"signature_request":{"signature_request_id":"fa5c8a0b0f492d768749333ad6fcc214c111e967","title":"My first request"}}'

echo -n $json | openssl dgst -sha256 -hmac $signing_secret
# Expected X-Signature: 3810cb411041efab279d31698b9584372e5ede9d1641fbb354810f16e51be81c

​
Respond to events

Your endpoint must return HTTP 200 OK within 30 seconds of receiving a request. No response body is required. 
HTTP/1.1 200 OK
Content-Type: application/json

{}
Acknowledge the request immediately and process the event asynchronously in a background job. This ensures you stay within the 30-second response window.

​
Error handling and retries

If your endpoint does not return 200 OK, Lumin retries the delivery. The following conditions trigger a retry:
  • HTTP 4xx or 5xx response
  • No response within 30 seconds (timeout)
  • Connection failure
For the full retry schedule, see Retry schedule.