Webhooks

Outbound workspace webhooks#

LumenFlow can POST signed workspace events to an HTTPS endpoint you register. This is the Settings → Connections → Webhooks flow — not a separate incoming-webhook URL surface.

Configure a subscription#

1. Go to Settings → Connections → Webhooks
2. Click Add Webhook
3. Enter a public HTTPS destination URL
4. Save — LumenFlow generates a signing secret and shows it once

Store the signing secret immediately. It cannot be retrieved again; delete and recreate the subscription to rotate it.

v1 delivers the tool_invocation event kind (workspace tool runs recorded in the action log). Each event is delivered at most once on success, with retry on transient failures.

Test delivery#

Use Send test on a subscription card to POST a synthetic signed event through the same delivery path the worker uses. A successful test reaches your endpoint with a valid signature.

Destination rules (egress)#

Destinations must be HTTPS and resolve to a public address. Loopback (127.0.0.1, localhost) and private-network targets are refused at create/edit time and again at delivery time — they never enter the retry loop.

Event payload#

Each delivery is a JSON envelope:

• delivery_id — stable id for this delivery chain
• workspace_id — your workspace
• occurred_at — delivery timestamp (ISO-8601)
• events[] — one or more events with id, kind, occurredAt, and data

Webhook signing#

Every delivery includes:

• X-Lumenflow-Signature: sha256=<hex> — HMAC-SHA256, using your subscription secret, of <timestamp>.<raw body>
• X-Lumenflow-Delivery-Id — the envelope delivery_id
• X-Lumenflow-Timestamp — unix seconds used when signing

To verify a delivery, join the X-Lumenflow-Timestamp value, a dot and the raw request body. Compute HMAC-SHA256 of that string with your secret, and compare the hex digest with the value after sha256= in constant time. Reject any delivery whose timestamp is more than five minutes from your clock. That window is the replay guard. Verify the signature before you trust the payload.

Signature schemes by surface#

Engagement subscriptions use the same sha256= form as workspace webhooks. Job result callbacks are described in the Jobs lifecycle article in the Developer Guide.