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.
Subscribe an endpoint
Section titled “Subscribe an endpoint”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 every delivery
Section titled “Verify every delivery”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 });}/** * The verified event of a delivery, its id (the webhook-id header) added. * Throws when a header is missing, the timestamp is more than five minutes * away, or no `v1` signature is the HMAC-SHA256 of `{id}.{timestamp}.{body}` * with the secret. Verify the raw body, before any JSON parsing. */function lexopti_verify_webhook(string $payload, array $headers, string $secret, int $toleranceSeconds = 300): array{ $headers = array_change_key_case($headers, CASE_LOWER); $id = $headers['webhook-id'] ?? ''; $timestamp = $headers['webhook-timestamp'] ?? ''; $signatures = $headers['webhook-signature'] ?? ''; if ($id === '' || !ctype_digit($timestamp) || $signatures === '') { throw new UnexpectedValueException('Missing webhook headers.'); } if (abs(time() - (int) $timestamp) > $toleranceSeconds) { throw new UnexpectedValueException('The webhook timestamp is too old or too new.'); } $key = base64_decode(preg_replace('/^whsec_/', '', $secret), true); if ($key === false || $key === '') { throw new InvalidArgumentException('The webhook secret is not a whsec_ secret.'); } $expected = base64_encode(hash_hmac('sha256', "{$id}.{$timestamp}.{$payload}", $key, true)); // During a secret rotation a delivery carries one signature per secret. foreach (explode(' ', $signatures) as $signature) { [$version, $value] = array_pad(explode(',', $signature, 2), 2, ''); if ($version === 'v1' && hash_equals($expected, $value)) { return json_decode($payload, true, 512, JSON_THROW_ON_ERROR) + ['id' => $id]; } } throw new UnexpectedValueException('No valid webhook signature.');}from standardwebhooks.webhooks import Webhookevent = Webhook(secret).verify(raw_body, headers)var webhook = new StandardWebhook(secret);webhook.Verify(rawBody, request.Headers);Answer at once, then process
Section titled “Answer at once, then process”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.
Test the endpoint
Section titled “Test the endpoint”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.
Replay a delivery
Section titled “Replay a delivery”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).
Rotate the secret
Section titled “Rotate the secret”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.
Enable a disabled endpoint again
Section titled “Enable a disabled endpoint again”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.
Poll the events instead
Section titled “Poll the events instead”Without a public endpoint, or to catch up, read GET /v1/events:
- Start with
after=0(the oldest event kept, up to 30 days). - Process the events, then store the
positionof the last one. - Call again with
after=<that position>: at once whilehas_moreis true, otherwise every 10 to 60 seconds. - Deduplicate on
id.