Account Webhooks

The account-level webhook notifies you of events happening across your entire Workspace. It is configured under your Workspace’s Developer Settings and secured with your Primary API key.

This model is best for single-tenant integrations, such as internal tools, where a Workspace admin wants centralized visibility of all activity.

Setting up Account webhooks

info

Only the Workspace Owner can create or update the Webhook URL.

To configure Account webhooks:

1. Go to Developer Settings page → API Key tab → Account callback section.
2. Enter your webhook URL (HTTPS required).
3. Click Save button.

Receiving Events

Once your Account webhook is configured, Lumin will automatically send HTTP POST requests to your endpoint when events occur.

Account webhooks receive all supported event types across your entire Workspace. For a complete list of available events, see Supported event types.

All webhook events follow a consistent JSON structure. For detailed payload examples, see Event payload structure.

Event delivery rules

• One request per event: Each event triggers a separate HTTP POST request
• Real-time delivery: Events are delivered as they occur
• Workspace-wide coverage: All events triggered by any API keys in your Workspace
• No filtering: You receive all event types - there's no opt-out mechanism

Verify the webhook

Lumin provides a couple of headers on Webhook requests:

User-Agent: Sender agent. Always Lumin Sign API.

X-Signature: A hex digest SHA256 signature of the request's JSON payload, generated using your Primary API key.

Verification steps:

1. Read the X-Signature header.
2. Compute HMAC-SHA256 with your Primary API key.
3. Compare securely with the header value.
4. Reject if mismatch or timestamp expired.

Example:

api_key='my_primary_api_key'
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 $api_key (X-Signature = 3810cb411041efab279d31698b9584372e5ede9d1641fbb354810f16e51be81c)

Respond to Events

Your webhook endpoint must respond appropriately to ensure reliable event delivery:

Success response

• Return HTTP 200 OK to acknowledge successful receipt
• Respond within 30 seconds to avoid timeout
• No specific response body required - empty response is acceptable

HTTP/1.1 200 OK
Content-Type: application/json

{}

Error handling

• HTTP 4xx/5xx responses will trigger retry attempts
• Timeout responses (>30 seconds) will be retried
• Connection failures will be retried with exponential backoff

For detailed retry schedules and failure handling, see Retry rules and failure handling.