Skip to content

Receive webhooks

This guide sets up an endpoint that receives LexOpti’s events, verifies them, and keeps working through failures. The event types, headers, retry schedule and endpoint rules are in events and deliveries.

Call POST /v1/webhook-endpoints with your url and the event_types you handle. The answer carries the signing secret (whsec_…) once: store it in your secret manager at once. A retry of the same request does not answer it again (409 idempotency_secret_withheld): rotate the secret instead.

Your application has at most 10 endpoints in each organization it is connected to, disabled ones included: another one answers 409 too_many_webhook_endpoints and creates nothing. Subscribe one endpoint to all the event types it handles rather than one endpoint per type, and delete the endpoints you no longer use (DELETE /v1/webhook-endpoints/{id}).

Verify the signature on the raw body, before any JSON parsing, and answer 400 when it is wrong. With the SDK, webhooks.verify throws when the signature, the timestamp or the payload is wrong. In PHP, the runnable PHP examples verify it with no library (or use Standard Webhooks’ PHP library); other languages use their Standard Webhooks library.

import { webhooks } from "@lexopti/sdk";
// A fetch handler (Bun, Deno, Next.js route): it throws on a wrong signature.
export async function POST(request: Request): Promise<Response> {
const event = webhooks.verify(
await request.text(),
request.headers,
process.env.LEXOPTI_WEBHOOK_SECRET ?? ""
);
console.log(event.id, event.type);
return new Response(null, { status: 204 });
}

Answer a 2xx as soon as the delivery is verified, and do the work afterwards: an attempt that takes longer than 15 seconds counts as failed and is retried. Deduplicate on the event id (webhook-id), which retries and replays keep. Read the client, check or alert through the API for the details: deliveries carry ids only.

POST /v1/webhook-endpoints/{id}/test sends a signed webhook.test. Accept it like an event, so the test passes, then read the attempt in GET /v1/webhook-endpoints/{id}/deliveries.

Find the delivery in GET /v1/webhook-endpoints/{id}/deliveries, then call POST /v1/webhook-endpoints/{id}/deliveries/{delivery_id}/replay. The replay keeps the event id: your deduplication ignores an event you already processed. The developer console shows the same deliveries, with each attempt and the body sent, and replays one from its Webhooks tab (logs and webhooks).

Call POST /v1/webhook-endpoints/{id}/rotate-secret and store the new secret it answers. The previous secrets keep signing for 24 hours: deploy the new one within that window, without downtime.

An endpoint that failed for a whole retry schedule is disabled (disabled_reason: failing). Fix it, then PATCH /v1/webhook-endpoints/{id} with enabled: true. Replay the deliveries you need, or read the events you missed from the feed, as below.

Without a public endpoint, or to catch up, read GET /v1/events:

  1. Start with after=0 (the oldest event kept, up to 30 days).
  2. Process the events, then store the position of the last one.
  3. Call again with after=<that position>: at once while has_more is true, otherwise every 10 to 60 seconds.
  4. Deduplicate on id.