Webhook reliability

Production integrations must assume at-least-once delivery: the same logical event may arrive more than once. This guide complements Handling webhooks with operational behavior.

Respond quickly, process async

Webhooks are delivered as plain HTTP POST requests. Your handler’s main job in the hot path is narrow: authenticate the payload (signature), persist or enqueue the minimum you need so you will not lose work, and return a success status to lomi. right away.

Return 2xx promptly after you validate the signature and persist enough to acknowledge receipt. Heavy work should run in your background queue. If you block on third-party APIs, large database transactions, or sequential business rules before responding, you risk exceeding lomi.’s outbound HTTP read timeout (approximately four seconds per attempt: see timeouts and retries). Keeping the HTTP response under a second in the common case leaves headroom for bursts and cold starts.

Idempotent processing

Use a stable event envelope id or a tuple of (event type, canonical resource id) to detect duplicates:

• If you have already applied the event, skip or no-op safely.
• Never assume “exactly once” without storing processed ids.

This matches server-side patterns where transaction updates merge metadata and balance updates check already processed flags.

Retries and delivery logs

Operational debugging almost always starts with what lomi. saw on the wire. Your endpoint’s response code, body snippet, and timings are written to webhook delivery logs, which you can read from the Dashboard or the Webhooks API. Use them to:

• confirm whether your endpoint returned non-2xx
• inspect latency and payload size
• debug signature or parsing issues

Repeated 401 Unauthorized attempts (often with a body such as "Authentication required") usually mean your server or CDN rejected the POST before webhook logic ran, outbound deliveries do not send Bearer/API-key auth ; see Signing secret vs Authorization headers.

Timeouts, retries, and client errors

The sections below describe how lomi. delivers webhooks today so you can plan for timeouts, retries, and non-retryable client errors. Product behavior can evolve; when in doubt, rely on delivery logs and idempotent handlers.

Per-attempt HTTP timeout

lomi.’s webhook HTTP client waits approximately 4 seconds (timeout: 4000 ms per request) for your server to finish the HTTP response.

• Aim to send 200 / 204 immediately after verifying X-Lomi-Signature (well under ~1 s), then enqueue business logic elsewhere.
• If you exceed ~4 s, from lomi.’s viewpoint the delivery failed due to timeout for that attempt (subject to retries, see below).

When lomi retries (and when it does not)

On each failed attempt, lomi. classifies the HTTP response as follows:

In practice: fix configuration and auth issues (which often surface as 4xx) before expecting automatic healing, lomi. will not keep retrying a misconfigured URL.

Retry attempt limits

For retryable failures (timeouts, 5xx, transient network faults), lomi. may attempt delivery up to four times on some paths, or up to five times when delivery is queued, with exponential backoff (initial delay about 3–5 seconds between attempts).

You do not need to distinguish delivery paths in your handler, always process events idempotently, but attempt counts help when you read delivery logs after an outage.

Payload envelope (lomi_environment)

The JSON field lomi_environment reflects the deployment environment (production, development, etc.). It is not a substitute for distinguishing live vs test traffic, use your API key environment and webhook endpoint configuration for that.

Signature verification

Verify using the raw request body bytes. Re-serialized JSON can break HMAC or similar schemes. Details: Handling webhooks and API integration.

Test vs live

Webhook endpoints and secrets are environment-specific. Promote configurations carefully so test URLs and secrets never receive live traffic.

Related API reference

• Webhooks API
• Payment state machine