Recevoir les webhooks
Ce guide met en place un point de réception qui reçoit les événements de LexOpti, les vérifie et continue de fonctionner malgré les échecs. Les types d’événements, les en-têtes, le calendrier des reprises et les règles des points de réception sont dans événements et envois.
Abonner un point de réception
Section intitulée « Abonner un point de réception »Appelez POST /v1/webhook-endpoints avec votre url et les event_types que vous traitez. La réponse contient une seule fois le secret de signature (whsec_…) : enregistrez-le aussitôt dans votre coffre de secrets. Une nouvelle tentative de la même requête ne le renvoie pas (409 idempotency_secret_withheld) : renouvelez alors le secret.
Votre application a au plus 10 points de réception dans chaque organisation à laquelle elle est connectée, désactivés compris : un de plus répond 409 too_many_webhook_endpoints et rien n’est créé. Abonnez un point de réception à tous les types d’événements qu’il traite plutôt qu’un point par type, et supprimez ceux dont vous ne vous servez plus (DELETE /v1/webhook-endpoints/{id}).
Vérifier chaque envoi
Section intitulée « Vérifier chaque envoi »Vérifiez la signature sur le corps brut, avant toute analyse JSON, et répondez 400 quand elle n’est pas valide. Avec le SDK, webhooks.verify lève une erreur quand la signature, l’horodatage ou le contenu n’est pas valide. En PHP, les exemples PHP exécutables la vérifient sans bibliothèque (ou utilisez la bibliothèque PHP de Standard Webhooks) ; les autres langages utilisent leur bibliothèque Standard Webhooks.
import { webhooks } from "@lexopti/sdk"; // Un gestionnaire fetch (Bun, Deno, route Next.js) : lève une erreur si la signature est fausse.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);Répondre aussitôt, traiter ensuite
Section intitulée « Répondre aussitôt, traiter ensuite »Répondez un 2xx dès que l’envoi est vérifié, et faites le travail ensuite : une tentative qui dure plus de 15 secondes compte comme un échec et est reprise. Dédoublonnez sur l’identifiant de l’événement (webhook-id), que les reprises et les rejeux conservent. Lisez le client, l’analyse ou l’alerte par l’API pour le détail : les envois ne portent que des identifiants.
Tester le point de réception
Section intitulée « Tester le point de réception »POST /v1/webhook-endpoints/{id}/test envoie un webhook.test signé. Acceptez-le comme un événement, pour que le test réussisse, puis lisez la tentative dans GET /v1/webhook-endpoints/{id}/deliveries.
Rejouer un envoi
Section intitulée « Rejouer un envoi »Trouvez l’envoi dans GET /v1/webhook-endpoints/{id}/deliveries, puis appelez POST /v1/webhook-endpoints/{id}/deliveries/{delivery_id}/replay. Le rejeu conserve l’identifiant de l’événement : votre dédoublonnage ignore un événement déjà traité. La console développeur montre les mêmes envois, avec chaque tentative et le corps envoyé, et en rejoue un depuis son onglet Webhooks (journaux et webhooks).
Renouveler le secret
Section intitulée « Renouveler le secret »Appelez POST /v1/webhook-endpoints/{id}/rotate-secret et enregistrez le nouveau secret qu’il répond. Les secrets précédents signent encore 24 heures : déployez le nouveau dans ce délai, sans interruption.
Réactiver un point de réception désactivé
Section intitulée « Réactiver un point de réception désactivé »Un point de réception en échec pendant tout un cycle de reprises est désactivé (disabled_reason: failing). Corrigez-le, puis PATCH /v1/webhook-endpoints/{id} avec enabled: true. Rejouez les envois dont vous avez besoin, ou lisez dans le flux les événements manqués, comme ci-dessous.
Interroger les événements à la place
Section intitulée « Interroger les événements à la place »Sans point de réception public, ou pour rattraper un retard, lisez GET /v1/events :
- Commencez avec
after=0(le plus ancien événement conservé, jusqu’à 30 jours). - Traitez les événements, puis enregistrez la
positiondu dernier. - Rappelez avec
after=<cette position>: aussitôt tant quehas_morevaut true, sinon toutes les 10 à 60 secondes. - Dédoublonnez sur
id.