(Livraison de webhooks · Nautilus)
Votre produit publie un événement en un appel d'API. Nautilus le met en file, le signe et le livre à chaque endpoint abonné à ce type d'événement. Une livraison échouée est retentée selon un calendrier fixe, et chaque tentative apparaît dans votre tableau de bord avec la réponse obtenue.
curl -X POST https://api.vernesoft.com/v1/relay/messages \
-H "Authorization: Bearer vrn_relay_•••" \
-d '{"event_type":"user.created","payload":{"id":"usr_123"}}'(Construire ou acheter)
La première version, c'est une requête POST dans une boucle de nouvelles tentatives. Cela cesse d'être simple quand le serveur d'un client est hors service tout un week-end, quand un déploiement de gestionnaire part cassé et qu'une heure d'événements doit être renvoyée, et quand un endpoint lent se met à retarder tous les autres.
Le construire soi-même
La livraison de webhooks dans Nautilus
(Fonctionnalités clés)
(01)
Une réponse autre que 2xx, ou un timeout, compte comme une tentative échouée. Le message est retenté à intervalles croissants : 8 tentatives sur environ 28 heures, le même calendrier pour chaque endpoint. La livraison est au moins une fois : un nouvel essai peut donc atteindre le serveur de votre client plus d'une fois.
(02)
Chaque message est signé en HMAC SHA-256 avec un secret propre à un endpoint. Chaque livraison porte trois en-têtes (svix-id, svix-timestamp et svix-signature), et la signature couvre l'identifiant, l'horodatage et le corps : vos clients peuvent vérifier l'expéditeur et rejeter une requête rejouée.
(03)
Publier un événement renvoie 202 dès que le message est en file. La livraison vers les serveurs de vos clients a lieu ensuite : un endpoint lent ou mort ne ralentit donc pas la requête que votre propre code attend.
(04)
Publiez un événement, par exemple user.created, et il est livré à chaque endpoint abonné à ce type d'événement. Ajoutez un canal à un message pour n'atteindre que les endpoints qui l'écoutent.
(05)
Chaque tentative est enregistrée avec son heure, le code de réponse et le corps de la réponse renvoyée par votre serveur, pour comprendre pourquoi une livraison a échoué. Dans l'onglet Events de votre tableau de bord, vous pouvez renvoyer une livraison, ou rejouer tout ce qui a échoué depuis un moment de votre choix, jusqu'à 14 jours en arrière.
(06)
Envoyez une idempotency_key et un appel répété renvoie le message d'origine au lieu d'en créer un second. La livraison, elle, est au moins une fois : un retry peut atteindre à nouveau vos clients, qui doivent donc dédupliquer sur l'en-tête svix-id, identique à chaque tentative pour un même message.
(Une partie de Nautilus)
La livraison de webhooks est une partie de Nautilus, pas un service à part. Elle partage un compte et un tableau de bord avec la connexion et les tâches cron. Les événements de connexion, comme une nouvelle inscription, arrivent sur votre backend de la même façon, en webhooks signés et retentés.
(Expérience développeur)
Publiez un événement en un seul appel — via un SDK officiel pour Node, Python, PHP ou Rust, ou par une simple requête HTTP si vous préférez éviter une dépendance.
curl -X POST https://api.vernesoft.com/v1/relay/messages \
-H "Authorization: Bearer $VERNE_RELAY_KEY" \
-H "Content-Type: application/json" \
-d '{
"event_type": "subscription.renewed",
"payload": { "user_id": "usr_987", "plan": "pro_tier" },
"idempotency_key": "evt_5f3c9a"
}'(FAQ)
Nautilus génère un secret unique pour chaque endpoint et signe chaque requête sortante en HMAC SHA-256. Chaque livraison porte trois en-têtes : svix-id, svix-timestamp et svix-signature. La signature est calculée sur svix-id, svix-timestamp et le corps brut, joints par des points, afin que le destinataire puisse vérifier l'authenticité et rejeter un rejeu. Les bibliothèques Svix officielles vérifient tout cela en un appel.
Toute réponse autre que 2xx, et tout timeout, compte comme une tentative échouée. Le message est retenté selon un calendrier fixe aux intervalles croissants, soit 8 tentatives sur environ 28 heures, ce qui évite de surcharger les serveurs en cours de récupération. Le calendrier est le même pour tous les endpoints et ne peut pas être modifié. Un endpoint qui échoue à chaque tentative pendant cinq jours est désactivé, et rien ne vous prévient : jetez donc un œil à l'onglet Events de temps en temps. Une fois votre serveur rétabli, vous pouvez renvoyer les livraisons échouées depuis le tableau de bord, ou rejouer tout ce qui a échoué depuis un moment de votre choix.
Oui. Exposez votre endpoint local avec un tunnel comme ngrok ou Cloudflare Tunnel et ajoutez cette URL comme endpoint dans le tableau de bord. Utilisez une clé live : les événements envoyés avec une clé de test sont acceptés mais pas livrés. Le journal de livraison vous permet d'inspecter chaque tentative pendant vos tests.
Vous le pouvez, et c'est bien plus qu'un POST : une file d'attente et un backoff exponentiel, des secrets par endpoint et la signature HMAC, un moyen de dédupliquer un envoi retenté, et un journal de livraison que votre support peut consulter quand un client dit que l'événement n'est jamais arrivé. Nautilus a cette liste toute faite, et vous payez à la requête d'API. Ce que vous cédez, c'est le contrôle : le calendrier de nouvelles tentatives est fixe, les endpoints s'ajoutent depuis le tableau de bord plutôt que par l'API, et le moteur en dessous est Svix, qui est open source si vous devez un jour l'exploiter vous-même.
Pas par l'API aujourd'hui. Les endpoints se créent dans le tableau de bord : si vous voulez que vos clients collent leur propre URL dans les réglages de votre produit, cet écran est à vous de le construire, et pour l'instant quelqu'un ayant accès au tableau de bord ajoute l'URL. Publier des événements et les relire sont possibles par l'API.
(Commencer)
La livraison de webhooks est une partie de Nautilus : le même compte et le même tableau de bord que la connexion et les tâches cron.
Ce que coûte de le construire
La construction n'est pas la partie chère. Une file d'attente, un retry avec backoff et un utilitaire de signature, c'est une semaine de travail, et la plupart des équipes y arrivent sans peine. La dépense commence la semaine suivante, quand un client affirme qu'un événement n'est jamais arrivé et que répondre signifie lire des logs à la main. Et cela ne s'arrête plus : chaque nouvel endpoint client est une nouvelle façon d'échouer à livrer.
Cela consomme aussi votre attention là où elle ne rapporte rien. Personne n'a choisi votre produit parce que vos retries utilisent un backoff exponentiel. Mais un webhook qui a cessé d'arriver en silence, c'est d'abord un ticket de support, puis une discussion sur un remboursement, parfois un client qui s'en va. Conséquences fortes, aucun crédit — exactement la forme d'une chose qu'on achète au lieu de la construire.
Si vous préférez le construire, construisez-le : la conception n'a rien de secret et nous ferions presque les mêmes choix. Comptez simplement un service que vous exploiterez pendant des années, pas un sprint. Si vous préférez ne pas le faire, un endpoint que vous avez déjà peut recevoir des livraisons signées et retentées dès que vous avez une clé d'API et que son URL est dans le tableau de bord, et les 3 000 premières requêtes de chaque mois sont offertes.