Aller au contenu

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.

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é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 });
}

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.

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.

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).

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.

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.

Sans point de réception public, ou pour rattraper un retard, lisez GET /v1/events :

  1. Commencez avec after=0 (le plus ancien événement conservé, jusqu’à 30 jours).
  2. Traitez les événements, puis enregistrez la position du dernier.
  3. Rappelez avec after=<cette position> : aussitôt tant que has_more vaut true, sinon toutes les 10 à 60 secondes.
  4. Dédoublonnez sur id.