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
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.
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êteX-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 :
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
- Test webhooks with the Webhook Tester — envois synthétiques non signés pour itérer
- Build your first webhook receiver — parcours complet du récepteur en Node et Python
- Build a durable webhook consumer — récepteur de production avec traitement en file