Guide

Hookdeck : une passerelle d'événements pour les webhooks

Hookdeck reçoit, met en file et rejoue tes webhooks entrants. État du projet, SDK gelés, CLI, règles de retry, signature, tarifs et alternatives.

L'équipe CodeWorlds20 min de lecture ·

Pratique HTML et CSS dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article9

Hookdeck est une passerelle d'événements hébergée : elle accepte les webhooks des fournisseurs, les met en file, relance la livraison selon des règles et stocke la charge utile de chaque requête pour inspection. Le service et l'outil en ligne de commande sont activement développés, mais les bibliothèques officielles pour les langages sont gelées depuis deux ans, donc la voie d'intégration recommandée aujourd'hui passe par de simples appels HTTP.

Ce que Hookdeck t'apporte par rapport à ton propre endpoint

Recevoir des webhooks ressemble à un contrôleur avec un seul POST. Les problèmes commencent plus tard, et ils sont tous du même genre : le fournisseur ne s'intéresse pas à l'état dans lequel se trouve ton application.

Le premier est les doublons. Stripe, Shopify ou GitHub renvoient le même événement si tu rates leur fenêtre de temps, et tu peux la rater à cause d'une migration de base de données sans rapport. Le deuxième est l'ordre : des événements order.updated peuvent arriver avant order.created parce qu'ils ont pris des chemins réseau différents. Le troisième est les pics de trafic. Une campagne génère mille webhooks par minute, ton serveur en traite cent, et après une série d'erreurs le fournisseur désactive l'endpoint. Le quatrième est la vérification des signatures, écrite séparément pour chaque fournisseur, chacun avec un en-tête et un schéma de condensat différents.

Hookdeck se place entre le fournisseur et ton API. Il accepte la requête et répond immédiatement au fournisseur, donc le fournisseur ne voit jamais ta panne. L'événement atterrit dans une file et est livré à la destination à une limite de débit que tu fixes toi-même. Si la destination dépasse 60 secondes, renvoie un code hors 2xx ou est injoignable, la règle de retry s'active. La charge utile de la requête est stockée pendant la période de rétention, donc tu peux l'inspecter, la rejouer ou la renvoyer une fois le bug corrigé.

S'ajoutent des choses que ton propre endpoint n'a généralement pas : le filtrage avant livraison, la déduplication sur des champs choisis de la charge utile, des transformations JavaScript et le transfert du trafic de production vers localhost pendant que tu travailles sur le code. Cette dernière fonctionnalité est parfois la seule raison pour laquelle des équipes ouvrent un compte.

État du projet : le service est vivant, les bibliothèques non

L'écart entre le rythme du service et l'état des bibliothèques est frappant ici, et il faut le connaître avant de brancher Hookdeck dans un produit.

L'outil en ligne de commande est développé. Le paquet npm hookdeck-cli est en version 2.5.0 du 13 août 2026, la précédente 2.4.0 est sortie le 7 août, et le tag beta pointe vers 3.0.0-beta.1 publiée le 21 août 2026. Le dépôt hookdeck/hookdeck-cli répond avec le code 200 et ne redirige pas ailleurs. Le service lui-même est en ligne aussi : hookdeck.com répond avec le code 200 et le pied de page indique Hookdeck Technologies Inc. avec l'année 2026.

La bibliothèque TypeScript est une autre histoire. Le paquet @hookdeck/sdk est en version 0.4.0 publiée le 21 août 2024, exactement il y a deux ans. C'est inférieur à un, donc les auteurs ne déclarent aucune stabilité d'interface, et pourtant aucune version n'a suivi. Le dépôt s'appelle hookdeck/hookdeck-typescript-sdk et il existe, alors que les variantes de nom hookdeck-sdk-typescript et hookdeck-python-sdk renvoient 404. Le code du SDK a été généré par Fern, et ses dépendances sont figées au niveau du correctif : node-fetch 2.7.0, qs 6.11.2, form-data 4.0.0, js-base64 3.7.2, url-join 4.0.1. Une épingle vieille de deux ans signifie qu'aucun correctif de sécurité ne t'atteint sans un remplacement manuel.

Le paquet @hookdeck/vercel, l'intégration pour la plateforme Vercel décrite dans l'article sur Next.js, est en version 0.3.1 du 29 octobre 2024 et dépend de @hookdeck/sdk dans la plage ^0.4.0. Il n'y a pas de conflit de plage : le SDK publié correspond à la plage que demande l'intégration. Les deux paquets se sont tus à la même période.

Il n'existe pas de client Python. Les noms hookdeck, hookdeck-sdk, hookdeck-python et hookdeck-cli renvoient tous 404 sur PyPI. Le fournisseur ne fait aucune annonce séparée, mais la documentation répond : la navigation n'a pas de section sur les bibliothèques, les exemples de signature en Python utilisent hmac, hashlib et base64 de la bibliothèque standard, et la référence de l'API mentionne la génération d'un SDK pour le langage de ton choix à partir des schémas OpenAPI. Le schéma est public à l'adresse https://api.hookdeck.com/2025-07-01/openapi, pèse environ 470 kilo-octets et décrit 89 chemins.

Pour mémoire : la même société maintient un second produit, Outpost, pour envoyer des webhooks, et là les bibliothèques sont vivantes. Le paquet @hookdeck/outpost-sdk est en version 1.5.0 du 24 juillet 2026, et un équivalent Python existe sur PyPI. Un fournisseur Terraform existe aussi dans le dépôt hookdeck/terraform-provider-hookdeck. Ce n'est donc pas que la société ne sait pas maintenir des bibliothèques. Ce qui est gelé, c'est précisément le client TypeScript de l'Event Gateway.

La conclusion pratique : aujourd'hui tu t'intègres à Hookdeck via REST et via la CLI, pas via le SDK. Si tu prends quand même @hookdeck/sdk, fige la version exacte, audite toi-même ses dépendances et attends-toi à ce que les nouveaux champs de l'API lui manquent.

Licence et ce qui se trouve vraiment dans les paquets publiés

J'ai vérifié la licence à partir de trois sources par paquet, car la déclaration du registre et le fichier du dépôt ne concordent pas toujours.

Pour hookdeck-cli, les trois sources concordent. Le champ npm license indique Apache-2.0, le LICENSE du dépôt contient le texte complet de l'Apache License 2.0, et l'archive 2.5.0 décompressée contient un LICENSE avec le même texte. Aucune variante d'orthographe comme LICENSE.md ou COPYING n'existe, seulement LICENSE. Le paquet contient du vrai code : le wrapper bin/hookdeck.js et un répertoire binaries avec des exécutables précompilés pour six plateformes, dont darwin-arm64, linux-amd64 et win32-amd64. Il n'a aucune dépendance d'exécution.

Pour @hookdeck/sdk, il y a un décalage, mais léger. Dans les métadonnées npm de la 0.4.0, le champ license n'existe pas, donc un outil qui collecte les licences de dépendances affiche ici une licence vide ou inconnue. L'archive décompressée contient bien un LICENSE avec le texte de l'Apache License 2.0, identique à celui du dépôt. Le contenu correspond à ce que déclare le dépôt, seul le champ du registre manque. Le code est là, avec les répertoires api, core, serialization et webhooks et un reference.md. Si tu tiens une liste des licences de dépendances dans ton entreprise, ce paquet doit être complété à la main.

Le paquet @hookdeck/vercel déclare Apache-2.0 dans le registre. Le paquet @hookdeck/outpost-sdk répète le schéma du champ perdu : il n'y a aucune licence dans les métadonnées npm, même si le code vient du dépôt hookdeck/outpost.

La licence ouverte ne couvre que l'outillage client. La passerelle elle-même est un service fermé, hébergé par le fournisseur, sans version à exécuter soi-même. Ce qui est ouvert, c'est le produit séparé Outpost, qui résout le problème inverse, envoyer des webhooks à tes propres clients. Si l'auto-hébergement est une exigence ferme pour toi, l'Event Gateway est exclu quels que soient les autres arguments.

L'outil en ligne de commande et le travail sur localhost

C'est la partie que les gens apprennent le plus vite. La CLI crée une URL permanente pour une source et transfère le trafic vers ton port local, sans reconfigurer le fournisseur à chaque exécution.

Bash
# install via npm, Homebrew or Scoop
npm install hookdeck-cli -g

# log in, opens a browser; in a terminal without one add --interactive
hookdeck login

# listen on one source, traffic goes to http://localhost:3000/webhooks/shopify
hookdeck listen 3000 shopify --path /webhooks/shopify

# listen on every source at once, plain logs instead of the full interface
hookdeck listen 3000 '*' --output compact

# only events matching a filter on the request body
hookdeck listen 3000 stripe --filter-body '{"type":"payment_intent.succeeded"}'

Le deuxième argument est l'alias de la source, et il accepte une liste séparée par des virgules ou '*'. Le troisième, facultatif, choisit une connexion précise par nom, alias ou chemin, et s'il n'en existe aucune il en crée une nouvelle. Le mode interactive par défaut est une interface plein écran avec une liste d'événements, où la touche r relance l'événement sélectionné, d affiche la requête et la réponse complètes, et o l'ouvre dans le tableau de bord du navigateur. Les modes compact et quiet conviennent à un processus en arrière-plan ou dans un pipeline d'intégration continue. L'option --max-connections plafonne les connexions simultanées au serveur local à 50 par défaut.

L'authentification par appel passe par les options --cli-key et --api-key. La première prend une clé liée à un utilisateur qui voit tous ses projets, la seconde une clé limitée à un seul projet. Sans connexion, la CLI crée un compte invité, pratique mais plus difficile à rattacher ensuite à la bonne organisation.

La CLI peut aussi gérer des ressources, pas seulement écouter. Le groupe hookdeck gateway connection crée et met à jour des connexions, hookdeck gateway transformation gère les transformations, et hookdeck gateway mcp démarre un serveur MCP qui permet à un agent dans ton éditeur d'inspecter les événements sans passer par le navigateur. Une image Docker existe aussi, où tu dois utiliser host.docker.internal au lieu de localhost.

Règles de connexion, filtres et vérification de signature

Une connexion relie une source à une destination et porte un tableau de règles. Les règles sont de cinq types : retry, filter, transform, delay et deduplicate. L'appel ci-dessous crée une connexion avec une règle de retry et une règle de déduplication.

Bash
curl -X PUT "https://api.hookdeck.com/2025-07-01/connections" \
  -H "Authorization: Bearer $HOOKDECK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "shopify-orders",
    "source": { "name": "shopify" },
    "destination": {
      "name": "orders-api",
      "config": {
        "url": "https://api.example.com/webhooks/shopify",
        "rate_limit": 100,
        "rate_limit_period": "minute"
      }
    },
    "rules": [
      {
        "type": "retry",
        "strategy": "exponential",
        "interval": 300000,
        "count": 5,
        "response_status_codes": [">=500", "!501"]
      },
      {
        "type": "deduplicate",
        "window": 60000,
        "include_fields": ["body.id", "body.order.number"]
      }
    ]
  }'

Le champ strategy accepte linear ou exponential. Avec une stratégie linéaire et un intervalle de 600000 millisecondes, les nouvelles tentatives tombent à la dixième, à la vingtième et à la trentième minute après l'échec. Avec une stratégie exponentielle et le même intervalle, elles tombent à la dixième, à la vingtième et à la quarantième. Le champ response_status_codes accepte des plages comme 500-599, des comparaisons comme >=500 et des exclusions comme !501, et en cas de contradiction la dernière correspondance l'emporte. La limite stricte est de 50 nouvelles tentatives automatiques par événement, tandis que les manuelles, tu peux les déclencher autant que tu veux, ce que couvre la documentation sur les retries avec la gestion de Retry-After. La fenêtre de déduplication se situe entre 1000 et 3600000 millisecondes, et include_fields prend en charge la notation par points et les indices de tableau, par exemple body.items[*].sku.

Les filtres sont une règle séparée avec une syntaxe séparée. Ils prennent du JSON comparé à headers, body, query ou path, avec les opérateurs $gte, $gt, $lt, $lte, $eq, $neq, $in, $nin, $startsWith, $endsWith, $or, $and, $ref, $exist et $not.

JSON
{
  "type": "filter",
  "body": {
    "$or": [
      { "type": { "$startsWith": "payment_intent." } },
      { "data": { "object": { "amount": { "$gte": 10000 } } } }
    ]
  }
}

Les filtres ont été conçus pour des charges utiles JSON. Pour du XML, seules de simples correspondances de texte fonctionneront, et le bon chemin passe par une transformation qui convertit la charge utile en JSON avant le filtre. Une requête rejetée par un filtre ne génère aucun événement, donc elle n'est pas facturée comme un événement mais comme une requête rejetée, ce qui compte pour la facture.

Une chose reste de ton côté : vérifier que la requête vient de Hookdeck et non de l'Internet ouvert. Le mode par défaut HOOKDECK_SIGNATURE ajoute un en-tête x-hookdeck-signature avec un condensat HMAC SHA-256 du corps brut, encodé en base64. Quand un secret est renouvelé avec un délai, un en-tête supplémentaire x-hookdeck-signature-2 porte l'ancienne clé.

JavaScript
import crypto from 'node:crypto'

export function isFromHookdeck(rawBody, headers) {
  const digest = crypto
    .createHmac('sha256', process.env.HOOKDECK_WEBHOOK_SECRET)
    .update(rawBody)
    .digest('base64')

  const primary = headers['x-hookdeck-signature']
  const secondary = headers['x-hookdeck-signature-2']

  return digest === primary || (Boolean(secondary) && digest === secondary)
}

Le détail clé : rawBody doit être exactement la suite d'octets qui est arrivée. Un framework qui analyse le JSON et le resérialise réordonnera les clés ou changera les espaces, et la signature ne correspondra plus. Pour l'authentification de la destination, tu peux aussi choisir BASIC_AUTH, API_KEY, BEARER_TOKEN, CUSTOM_SIGNATURE, AWS_SIGNATURE ou l'une des deux variantes OAuth2, si ton API a déjà son propre mécanisme.

Tarifs et facture pour cent mille événements

L'unité de facturation est un événement, c'est-à-dire un message livré à une destination. Une requête entrante et un événement sont deux choses différentes : une requête peut générer zéro, un ou plusieurs événements, selon le nombre de connexions et les filtres. Les retries sont inclus dans le prix d'un événement, ce qui est indiqué explicitement dans la section des questions de la page des tarifs.

Au 22 août 2026, les offres se présentent ainsi : Developer à 0 dollar, Team à partir de 39 dollars par mois, Growth à partir de 499 dollars par mois, et Enterprise à prix négocié. Dans les trois offres non négociées, le quota d'événements inclus est le même, 10 000 par mois, les requêtes rejetées incluses sont 100 000, et les requêtes rejetées supplémentaires coûtent 2,50 dollars par million. Les différences se trouvent ailleurs : la rétention est de 3 jours, 7 jours et 30 jours, le nombre d'utilisateurs est un puis illimité, et le SLA de disponibilité de 99,999 pour cent avec le SLA de latence de 99,99 pour cent n'apparaît que dans l'offre Growth. L'option d'IP statique coûte 100 dollars dans chaque offre.

La facture pour cent mille événements par mois sur l'offre Team demande de la prudence, car le fournisseur cite trois tarifs différents au même endroit. Le titre du calculateur parle d'un prix « as low as 0.33 dollars per 100k ». Le balisage statique du calculateur, avec le curseur à 10 000, affiche « 1.00 dollars per additional 100k ». La section des questions, elle, donne un exemple explicite : la facturation est quantifiée par blocs de 10 mille, 10 001 événements coûtent 0,30 dollar et 20 001 événements coûtent 0,60 dollar. Ce troisième tarif revient à 3,00 dollars pour 100 mille, neuf fois le premier. Le calculateur est un curseur rendu dans le navigateur, donc la source brute de la page ne donne que l'état par défaut et je ne peux pas établir à partir de quel volume le tarif de 0,33 s'applique.

En comptant avec le seul tarif énoncé explicitement dans l'exemple : 100 000 événements moins les 10 000 inclus laissent 90 000 événements supplémentaires, soit 9 blocs de dix mille, soit 2,70 dollars. Avec l'abonnement, cela fait 41,70 dollars par mois. Au tarif du calculateur, ce serait environ 39,90 dollars, et au tarif du titre environ 39,30. L'écart est donc étroit et à ce volume le coût est de l'ordre de quarante dollars, mais la divergence doit être confirmée avec le fournisseur avant de signer pour un trafic plus important, car à dix millions d'événements la différence entre 0,33 et 3,00 par cent mille représente la différence entre 33 et 300 dollars d'usage à elle seule.

Reste le débit. Le prix inclut 5 événements par seconde par destination dans un projet, ce qui, avec une répartition uniforme, donne 432 000 événements par jour et à cent mille par mois ne représente aucune contrainte. Cela devient une contrainte pendant les pics : tout ce qui dépasse le plafond n'est pas rejeté mais mis en file, donc tu paies en latence plutôt qu'en événements perdus. Les requêtes entrantes sont toujours acceptées.

L'offre gratuite a une clause facile à manquer. Au-delà de 10 000 événements, les événements continuent d'être acceptés, mais le tableau de bord est verrouillé jusqu'à ce que tu changes d'offre ou qu'une nouvelle période de facturation commence, et en cas de dépassement excessif le fournisseur se réserve le droit d'arrêter le traitement. Une rétention de trois jours sur l'offre gratuite signifie aussi qu'après un week-end tu ne rejoueras pas les événements de vendredi.

Hookdeck face à Inngest, Trigger.dev, Svix et Pipedream

Ces noms apparaissent dans la même phrase plus souvent qu'ils ne le devraient, car ils résolvent des problèmes différents.

OutilRôleSens de l'événementOù s'exécute ton code
Hookdeck Event Gatewaypasserelle pour les webhooks entrantsde l'extérieur vers ton APIuniquement de ton côté
Svixinfrastructure de webhooks sortantsde ton API vers les clientsuniquement de ton côté
Inngestfile de tâches et flux pilotés par événementsà l'intérieur de ton propre systèmefonctions de ton côté, orchestration chez le fournisseur
Trigger.devtâches de fond de longue duréeà l'intérieur de ton propre systèmetâches sur l'infrastructure du fournisseur
Pipedreamautomatisation avec étapes et intégrationsde l'extérieur vers l'extérieurétapes chez le fournisseur

Inngest et Trigger.dev sont des files de tâches. Leur centre de gravité se situe dans ce qui se passe après la réception d'un événement : étapes, reprise, délais, concurrence. Hookdeck se place une étape plus tôt et n'exécute pas ta logique, il y amène seulement le trafic. Ces outils ne s'excluent pas : Hookdeck peut accepter un webhook et le transmettre à un endpoint qui met une tâche en file dans Inngest.

Pipedream combine la réception d'événements avec l'automatisation, un peu comme Zapier, décrit séparément, mais avec du code au lieu de clics. Si, après avoir reçu un webhook, tu dois ajouter une ligne de tableur et envoyer un message, Pipedream fera tout. Si tu dois remettre l'événement à ta propre API avec des garanties de livraison, Pipedream est le chemin le plus long.

Svix est un concurrent direct, mais de l'autre côté de la flèche : il construit l'infrastructure pour envoyer des webhooks à tes clients. L'équivalent Hookdeck de Svix n'est pas l'Event Gateway mais Outpost. Si tu cherches un outil d'envoi, compare Svix avec Outpost plutôt qu'avec la passerelle décrite ici.

Erreurs courantes

La première est de prendre @hookdeck/sdk par réflexe, parce que le paquet existe. La version 0.4.0 d'août 2024 ne sait rien des champs ajoutés à l'API en deux ans, et ses dépendances figées entraînent un vieux node-fetch. Un simple fetch avec le jeton dans l'en-tête Authorization est plus court et plus actuel aujourd'hui.

La deuxième est d'analyser le corps avant de vérifier la signature. Dans Express, cela veut dire garder le corps brut dans un champ rawBody, dans Next.js prendre await request.text() au lieu de await request.json(). La signature est calculée sur des octets, pas sur un objet.

La troisième est de traiter les retries comme une garantie qu'un événement sera traité exactement une fois. Ce ne sera pas le cas. La déduplication dans Hookdeck fonctionne dans une fenêtre d'au plus une heure et sur des champs choisis, et un retry deux jours plus tard arrivera à nouveau. L'idempotence côté réception, ne serait-ce que par un index unique sur l'identifiant de l'événement dans PostgreSQL, reste ton travail.

La quatrième est de fixer une règle de retry exponentielle avec un grand intervalle sans vérifier la rétention. Des retries répartis sur une journée entière face à la rétention de trois jours de l'offre gratuite laissent une fenêtre étroite pour une correction manuelle.

La cinquième est d'installer une passerelle là où elle n'est pas nécessaire. Avec quelques centaines d'événements par jour et un seul fournisseur, une table dans la base de données, une colonne de statut et une tâche cron qui relance les lignes en échec règlent la question gratuitement et sans dépendance externe. Hookdeck commence à se rentabiliser quand il y a plusieurs fournisseurs, que le trafic arrive en pics et que quelqu'un doit pouvoir inspecter une charge utile d'il y a trois jours sans fouiller les journaux du serveur.

La sixième est de sous-estimer le verrouillage chez le fournisseur. Les URL des sources appartiennent à Hookdeck et sont écrites dans la configuration de chaque fournisseur d'événements. Partir signifie changer l'adresse dans Stripe, Shopify et chaque autre tableau de bord, et les transformations écrites en JavaScript et stockées côté fournisseur doivent être réécrites. La configuration peut être exportée via l'API et conservée dans le fournisseur Terraform, ce qui est un moyen sensé de plafonner le coût du départ.

FAQ

Hookdeck a-t-il une bibliothèque Python officielle ?

Non. Aucun paquet n'existe sur PyPI sous les noms hookdeck, hookdeck-sdk ou hookdeck-python. La documentation montre des exemples construits sur hmac, hashlib et base64 de la bibliothèque standard et indique de générer un client à partir du schéma OpenAPI servi à l'adresse de l'API.

@hookdeck/sdk vaut-il la peine dans un nouveau projet ?

Dans la plupart des cas, non. Le paquet est en version 0.4.0 du 21 août 2024, inférieure à un, et porte des dépendances figées vieilles de deux ans. Les appels REST avec le jeton dans un en-tête Authorization: Bearer te donnent accès à l'API complète et à jour. L'exception est la fonction verifyWebhookSignature du module webhooks, mais elle se résume à quelques lignes de node:crypto que tu peux tout aussi bien écrire toi-même.

Peut-on exécuter Hookdeck sur son propre serveur ?

L'Event Gateway, non. C'est un service fermé hébergé par le fournisseur, et la licence Apache 2.0 ne couvre que l'outil en ligne de commande et les bibliothèques clientes. Ce qui est ouvert, c'est le produit séparé Outpost dans le dépôt hookdeck/outpost, mais il résout le problème inverse, envoyer des webhooks à tes propres clients.

Combien coûtent cent mille événements par mois ?

Sur l'offre Team, environ 41,70 dollars, en comptant 39 dollars d'abonnement plus 2,70 dollars pour 90 mille événements au-delà du quota au tarif de 0,30 dollar par 10 mille indiqué dans la section des questions. Le fournisseur cite deux autres tarifs au même endroit, 1,00 et 0,33 dollar par 100 mille, donc pour de plus gros volumes, confirme le prix avec lui.

Hookdeck garantit-il l'ordre des événements ?

Pas au sens d'un ordre global strict. La mise en file avec une limite de débit par destination lisse le trafic, mais le retry d'un événement en échec arrivera après des événements plus récents. Si l'ordre compte, il te faut un marqueur de version ou d'horodatage dans la charge utile et une règle qui écarte les états plus anciens que celui déjà stocké.

Quand ta propre file suffit-elle à la place d'une passerelle ?

Quand tu as un fournisseur, quelques centaines d'événements par jour et un trafic prévisible. Une table d'événements dans la base de données, une colonne de statut, un index unique sur l'identifiant et une tâche cron qui relance les lignes en échec représentent une soirée de travail. L'intérêt d'une passerelle apparaît avec plusieurs fournisseurs, un trafic en pics et le besoin que des personnes extérieures à l'équipe inspectent les charges utiles.

À lire aussi