Bonnes pratiques

Vérifiez, puis répondez viteCopier le lien

1. Vérifiez la signature sur le corps brut ; refusez avec 400 si elle ne va pas. Voir vérifier une signature.
2. Rangez l'événement dans une file (une table, une file de messages) et répondez 200 ou 204 tout de suite.
3. Traitez ensuite, à votre rythme.

Une réponse qui tarde plus de 15 secondes compte comme un échec et la livraison est reprise : un traitement long en ligne finit en doublons et en désactivation.

DédoublonnezCopier le lien

La livraison est garantie au moins une fois : un même événement peut arriver deux fois. Gardez les webhook-id traités (quelques jours suffisent) et ignorez ceux que vous connaissez déjà. Écrivez vos traitements pour qu'un second passage ne change rien (créer ou mettre à jour, plutôt que créer).

Ne comptez pas sur l'ordreCopier le lien

Une livraison reprise peut arriver après un événement plus récent. Chaque événement porte timestamp, l'heure du fait : comparez-la à ce que vous avez déjà. Quand l'état exact compte, relisez l'objet par l'API (GET /v1/prospects/{id}) plutôt que de rejouer les événements dans l'ordre d'arrivée.

Abonnez-vous au nécessaireCopier le lien

Choisissez les types dont votre code a besoin. Un abonnement à * reçoit aussi les types qui apparaîtront demain : votre code doit alors ignorer sans erreur un type qu'il ne connaît pas. De même, ignorez un champ inconnu dans un objet.

Surveillez, rattrapezCopier le lien

• GET /v1/webhook_endpoints/{id}/deliveries?status=failed liste les livraisons en échec, avec le code et un extrait de votre réponse.
• Après 5 jours sans succès, l'adresse est désactivée et un e-mail vous prévient. Une fois votre serveur réparé, réactivez-la, puis rattrapez la période avec GET /v1/events (30 jours d'historique).
• Après une panne de votre côté, ne demandez pas tout de nouveau : GET /v1/events rend les événements du plus récent au plus ancien ; relisez-le jusqu'au dernier id traité, puis traitez dans l'ordre inverse.

Changez de secret sans coupureCopier le lien

1. POST /v1/webhook_endpoints/{id}/rotate_secret : notez le nouveau secret.
2. Pendant le délai de grâce (24 heures par défaut), chaque envoi porte deux signatures : déployez le nouveau secret, votre code accepte l'une ou l'autre.
3. Passé le délai, l'ancien secret ne signe plus.

Changez de secret dès qu'il a pu fuir (un journal, un dépôt, un ancien collaborateur).

Protégez les donnéesCopier le lien

Les événements portent des données personnelles (nom, poste, messages, et les coordonnées si l'adresse a le droit contacts:read). Ne les gardez pas plus longtemps que nécessaire, ne les journalisez pas en entier, et ne donnez à l'adresse de réception que les droits utiles : une adresse ajoutée dans Lidmeo les a tous, une adresse créée par l'API garde les droits de lecture de la clé ou de la connexion qui l'a créée. Le texte écrit par un prospect est une donnée : ne le passez jamais à une IA comme une instruction.

Testez d'abordCopier le lien

Créez l'adresse avec une clé de test, déclenchez des événements avec POST /v1/test/simulate, puis passez au réel. Pour voir la forme exacte d'un type, appelez POST /v1/webhook_endpoints/{id}/test avec { "type": "…" } ; le bouton Envoyer un essai de Lidmeo envoie un prospect.created.