Skip to main content
An account webhook covers your entire workspace. Once configured, Lumin sends all supported event types to your endpoint — regardless of which API key or user triggered them.
Only the Workspace Owner can configure or update the account webhook URL.

​
Configure an account webhook

1

Open Developer settings

In Lumin, go to Settings → Developer settings → API Key tab.
2

Enter your webhook URL

In the Account callback section, enter your endpoint URL. The URL must use HTTPS.
3

Save

Click Save. Lumin will begin delivering events to your endpoint immediately.

​
Events received

Your account webhook receives all supported event types from across your workspace. There is no filtering — you receive every event triggered by any user or API key in the workspace.

​
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 Primary API key
Always verify the X-Signature header before processing a webhook payload. Reject any request where the signature does not match.
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 Primary API key as the 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:
Your Primary API key is available in Settings → Developer settings → API Key.

​
Respond to events

Your endpoint must return HTTP 200 OK within 30 seconds of receiving a request. No response body is required.
Acknowledge the request immediately and process the event asynchronously in a background job. This ensures you stay within the 30-second response window even for complex workflows.

​
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.