Build an email webhook receiver that queues work safely

Keep ingress smaller than the agent

A webhook receiver should authenticate an event, validate its envelope and place a bounded job into durable storage. It should not run an entire model conversation before responding. Long-running handlers make delivery retries and timeouts difficult to interpret, especially when the eventual job can create external side effects. Configure POST /v0/webhooks with an HTTPS URL and the narrow event_types your application needs, such as email.received. Add inbox_ids or project_ids when a receiver should serve only selected resources rather than every message in the organization.

Verify before trusting the payload

Lupin deliveries use svix-id, svix-timestamp and svix-signature headers with the exact raw request body. Preserve those bytes through your framework and reverse proxy; parsing and reserializing JSON can invalidate verification. Use a maintained Svix verifier or the checked-in verifier when you have repository access. Reject missing, invalid or stale signatures before selecting an account, parsing instructions or enqueueing work. Custom tenant headers can help route already authenticated traffic, but they are not a replacement for signature verification or your own resource ownership check.

Bind the event to a known tenant

Maintain a local mapping from the webhook configuration and trusted inbox IDs to your application tenant. Check the received resource against that mapping rather than allowing an event body to choose an arbitrary organization credential. Treat identifiers as references to verify, not proof of authority. Bound body size, validate the expected event_type and distinguish normal email.received from spam, blocked and unauthenticated variants. Decide explicitly which variants become jobs. A quarantined message can be useful for abuse investigation without belonging in the ordinary auto-drafting queue.

Make acknowledgment mean durable acceptance

Deduplicate on a stable delivered event identity and save the queue record before returning a success response. Repeated delivery of an already queued event should acknowledge the existing work rather than start a second run. If your queue is unavailable, return an appropriate failure so the delivery system can observe that the handoff did not complete. Keep agent processing status separate from webhook delivery status: a successfully accepted webhook may still lead to a failed classifier or a draft waiting for review. Your monitoring should expose both boundaries.

Keep secrets and replay controls operational

Store signing secrets and custom authorization headers in a private secret manager. Lupin custom header values are write-only; reads list names without returning values, and header updates can atomically set and remove names. Plan rotation so old and new signatures can be accepted during a bounded transition where supported. Do not log raw bodies containing private correspondence simply to troubleshoot retries. Your next step is a local receiver fixture that submits valid, altered, expired and duplicate deliveries and verifies that only one durable job is produced, with no real outbound message or tool execution.

Separate delivery IDs from message IDs

The verified webhook delivery identity helps deduplicate ingress attempts, while the contained email identity helps deduplicate business processing across polling and events. Save both when available. If your queue uses only delivery identity, a later backfill may still process the same email again; if it uses only email identity, distinct relevant event transitions may be lost.

Sources & verification

Reviewed against checked-in Lupin API handlers and documentation. Example requests were not executed against live providers.

• Lupin webhooks ↗Checked 2026-11-05
• Svix webhook verification ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.