Skip to main content

Note de langue

Cette version française est une traduction abrégée : la section « Step 6 — Move to an event sink when you outgrow HTTP receivers » n’existe qu’en anglais : /en/guides/first-webhook-quickstart. Les blocs de code, chemins d’endpoints, noms de champs API et codes d’erreur restent en anglais.

Quickstart : recevoir votre premier webhook

Trois surfaces de livraison sortent les événements Orbit de la plateforme ; ce guide vous aide à en choisir une, puis parcourt la boucle complète de l’endpoint enregistré — tunnel, enregistrement, vérification, replay.

Step 1 — Choisir une surface de livraison

Commencez avec le Tester pendant vos expérimentations. Passez à un endpoint enregistré dès que l’intégration devient réelle — le tester ne signe pas les requêtes et n’exerce donc jamais votre logique de vérification.

Step 2 — Exposer un endpoint local avec un tunnel

Copiez l’URL HTTPS de transfert — c’est l’adresse que vous enregistrerez à l’étape suivante. Gardez le tunnel actif pendant l’enregistrement et le replay.

Step 3 — Enregistrer l’endpoint dans la console (ou via l’API)

Dans le dashboard, allez à Developer → Webhooks → Add endpoint. Collez l’URL de votre tunnel, abonnez-vous à un ou deux types d’événements et enregistrez. La console montre le secret de signature en clair (whsec_...) exactement une fois — copiez-le maintenant dans une variable d’environnement.
La réponse porte l’identifiant de votre endpoint (wh_...) et le secret en clair à usage unique (whsec_...) — persistez-le maintenant, car tout GET ultérieur sur l’endpoint ne rend qu’une valeur masquée. Des listes events étroites gardent le trafic de test raisonnable ; * est une décision de production, pas de développement.

Step 4 — Recevoir et vérifier la signature

Les livraisons enregistrées arrivent signées avec un en-tête X-Orbit-Signature au format t=<unix>,v1=<hex>. Votre récepteur doit vérifier HMAC_SHA256(secret, "<t>.<raw body>") sur les octets bruts de la requête — avant tout middleware JSON — et rejeter les horodatages de plus de 5 minutes. Une vérification Node minimale :
Rendez 2xx dans la fenêtre de livraison de 30 secondes et dédupliquez sur l’id de l’enveloppe — reprises et replays relivrent le même id. Le contrat complet (calendrier de reprises, dead-letter queue) est sur Webhooks overview.

Step 5 — Rejouer les livraisons depuis la console

Chaque tentative de livraison est inspectable sous Developer → Webhooks → Events — choisissez une ligne pour voir le payload et la réponse rendue par votre serveur. Une livraison échouée se renvoie avec Replay sur la ligne, ce qui vous permet de corriger votre récepteur et de retiquer le même événement signé sans déclencher de nouveau trafic. Les livraisons qui épuisent le calendrier de reprises atterrissent dans la dead-letter queue sous Developer → Webhooks → Dead-letter queue, rejouables pendant 7 jours.

Voir aussi