Un webhook est une adresse de votre système que Hermetry appelle lorsqu’un événement se produit. Utilisez-le pour alimenter un système de tickets, un ERP, un bus de messages ou votre propre service. Les webhooks sont gérés par les administrateurs dans Webhooks (dans la partie Developer du menu). L’envoi de webhooks nécessite un forfait qui les inclut.
Créer un webhook
- Ouvrez Webhooks et sélectionnez New Webhook.
- Saisissez un Name et, facultativement, une Description (« À quoi sert ce webhook ? »).
- Saisissez l’URL. Elle doit être en HTTPS : « Webhook URL must be a valid HTTPS URL. »
- Sous Events, choisissez au moins un événement. La liste n’affiche que les événements des modules utilisés par votre organisation.
- Facultativement :
- Custom headers (optional) : jusqu’à 20 en-têtes envoyés à chaque appel, par exemple un jeton d’autorisation que votre récepteur vérifie.
Content-Type,User-Agent,Host,Content-LengthetX-Webhook-*ne peuvent pas être définis. Les valeurs tiennent sur une ligne, à 1 000 caractères maximum. - Event filters (optional, advanced) : ne livrer un événement que lorsque son contenu correspond (voir ci-dessous).
- Tags (optional, comma-separated) : étiquettes pour organiser vos webhooks, 20 maximum.
- Rate limit (optional, deliveries/minute) : vide signifie illimité.
- Custom headers (optional) : jusqu’à 20 en-têtes envoyés à chaque appel, par exemple un jeton d’autorisation que votre récepteur vérifie.
- Enregistrez. Copiez le Signing secret maintenant : il n’est affiché qu’une seule fois.
Tous les événements des modules IoT sont listés avec des exemples de contenu dans la Webhook event reference.
Filtres d’événements
Un filtre d’événement est un objet JSON qui associe un événement aux champs du contenu qu’il doit respecter. Une livraison est ignorée lorsque le contenu ne correspond pas. Les événements sans filtre sont toujours livrés.
{
"alarm.created": { "severity": "CRITICAL" },
"device.disconnected": { "profileId": "6f1c0a2e-0000-4000-8000-000000000001" }
}
Chaque chemin désigne un champ de data de l’événement et peut être pointé, par exemple originator.type. Chaque champ listé doit être égal à sa valeur (nombres et textes sont comparés comme du texte, donc "2" correspond à 2). 50 événements au maximum peuvent avoir un filtre.
À quoi ressemble une livraison
Hermetry envoie un POST avec ces en-têtes :
| En-tête | Valeur |
|---|---|
Content-Type | application/json (format par défaut) ou application/cloudevents+json; charset=utf-8 |
User-Agent | Hermetry-Webhooks/1.0 |
X-Webhook-Event | Le nom de l’événement, par exemple device.disconnected |
X-Webhook-Delivery | L’identifiant de la livraison. Identique à chaque nouvelle tentative et à chaque renvoi d’une même livraison. |
X-Webhook-Timestamp | Secondes Unix au moment où cette tentative a été signée |
X-Webhook-Signature-V2 | sha256= + HMAC-SHA256 de "<timestamp>.<body>" avec votre secret. Utilisez celui-ci. |
X-Webhook-Signature | HMAC-SHA256 du seul corps. Ancienne forme, conservée pendant une période de transition. |
X-Webhook-Signature-Prev, X-Webhook-Signature-V2-Prev | Les mêmes, avec le secret précédent, pendant une rotation de secret |
X-Webhook-Manual | true sur un événement envoyé manuellement par un administrateur |
X-Idempotency-Key | Sur les messages qu’un flux envoie avec son bloc webhook |
Avec le format par défaut, le corps est une enveloppe :
{
"webhookId": "…",
"tenantId": "…",
"event": "device.disconnected",
"createdAt": "2026-11-03T12:00:30.000Z",
"data": { "deviceId": "…", "name": "router-17", "reason": "timeout", "…": "…" }
}
Un événement envoyé manuellement par un administrateur comporte aussi "manual": true. Répondez par n’importe quel statut 2xx dans le délai imparti. Les 4 premiers Ko du corps de votre réponse sont conservés dans le journal des livraisons.
Format CloudEvents
Un point de terminaison peut recevoir à la place des CloudEvents 1.0 en mode structuré. Définissez "format": "cloudevents" via l’API (POST ou PATCH /api/webhooks/..., voir ci-dessous). "json" est la valeur par défaut.
{
"specversion": "1.0",
"id": "8d2c…",
"source": "urn:hermetry:tenant:<tenantId>",
"type": "com.hermetry.device.connected",
"datacontenttype": "application/json",
"time": "2026-11-03T10:00:30.000Z",
"data": { "deviceId": "…", "name": "router-17", "transport": "mqtts", "…": "…" },
"tenantid": "<tenantId>",
"webhookid": "<webhookId>"
}
data contient exactement ce que le format par défaut contient sous data. id est identique à chaque nouvelle tentative et à chaque renvoi, dédupliquez donc sur source et id. Les en-têtes de signature sont identiques dans les deux formats. Les modes batch et binaire ne sont pas proposés.
Vérifier la signature
Vérifiez sur le corps brut, avant de l’analyser, et rejetez les horodatages anciens.
import crypto from 'crypto';
function verifyWebhook(body: string, timestamp: string, signatureV2: string, secret: string): boolean {
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex');
// Reject deliveries older than 5 minutes.
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const a = Buffer.from(expected);
const b = Buffer.from(signatureV2);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
Pendant une rotation de secret, acceptez un appel lorsque X-Webhook-Signature-V2 ou X-Webhook-Signature-V2-Prev correspond.
Livraison, nouvelles tentatives et lettres mortes
| Paramètre | Par défaut | Plage |
|---|---|---|
| Request Timeout (ms) | 15,000 | 1 000 à 120 000 |
| Max Delivery Attempts (la première incluse) | 3 | 1 à 10 |
| Retry Backoff (ms) : l’attente avant la nouvelle tentative 1, 2, … | 60000,300000,900000 | 1 à 9 valeurs, chacune de 1 000 à 86 400 000 ; au-delà de la liste, la dernière valeur |
| Circuit Breaker Threshold : nombre d’échecs consécutifs avant la désactivation du point de terminaison | 10 | 1 à 100 000 |
| Default Rate Limit (per minute) : pour les points de terminaison sans limite propre | illimité | vide ou 0 = illimité |
Réglez-les dans Webhooks > paramètres (le bouton en forme d’engrenage). Une livraison est l’un des statuts suivants : PENDING, SUCCESS, FAILED (sera retentée) ou DEAD_LETTERED (toutes les tentatives utilisées).
- Chaque livraison est journalisée avec son statut, ses tentatives, son code de réponse, son erreur, sa durée et l’heure de la prochaine tentative.
- Un point de terminaison au-delà de sa limite de débit reçoit ses livraisons environ 60 secondes plus tard ; rien n’est perdu.
- Après le seuil d’échecs consécutifs, le point de terminaison est désactivé et apparaît comme désactivé automatiquement. Les nouvelles tentatives en file d’attente s’arrêtent. Réactivez-le pour réinitialiser le compteur, puis renvoyez ou rejouez ce qui a échoué.
- Les livraisons sont effectuées au moins une fois. Dédupliquez sur
X-Webhook-Delivery(ou sur l’idCloudEvents). - L’ordre d’arrivée des événements n’est pas garanti. Utilisez les heures figurant dans le contenu.
Les événements de connexion et de modification des appareils ont leur propre garde-fou de volume : 600 de chaque type par organisation et par minute au maximum, par défaut. Voir la Webhook event reference.
Renouveler le secret
Sélectionnez Rotate signing secret (rôle Owner). Le nouveau secret n’est affiché qu’une fois. L’ancien secret reste valide pendant 48 heures ; pendant ce temps, chaque appel porte les deux signatures. Renouveler à nouveau pendant cette fenêtre ne remplace que le secret actuel ; le précédent conserve sa date de fin.
Tester
Depuis les actions de ligne d’un webhook ou depuis sa page :
- Send test event envoie immédiatement un événement nommé
testet affiche le résultat (« Test delivered — HTTP 200 in 85 ms »). Un test ne compte jamais dans le disjoncteur. - Trigger event… envoie un véritable événement signé de votre choix avec un exemple de contenu (objet JSON, 64 Ko maximum), marqué
manual: trueetX-Webhook-Manual: true. Il respecte le filtre d’événements du point de terminaison : un exemple que le filtre écarterait est refusé. - View deliveries affiche les livraisons ; une livraison échouée ou en lettre morte peut être renvoyée, et toutes les lettres mortes peuvent être rejouées en une fois.
Règles réseau
Les adresses de webhook doivent être des adresses HTTPS publiques. Les adresses privées, de boucle locale, à liaison locale et de métadonnées cloud sont refusées à l’enregistrement puis à chaque appel, et les redirections ne sont pas suivies. Pour une cible interne voulue, un administrateur peut définir via l’API une ipAllowlist explicite (jusqu’à 50 adresses ou plages CIDR) sur le webhook.
L’API des webhooks
Les chemins sont sous /tenant/<tenantId>. Tous nécessitent les droits d’un administrateur.
| Méthode | Chemin | Fonction |
|---|---|---|
| GET | /api/webhooks/events | Les événements auxquels vous pouvez vous abonner |
| GET, POST | /api/webhooks | Liste (page à partir de 1, pageSize, search, sort, isActive, autoDisabled) ; création : 201 { webhook, secret } |
| GET, PATCH, DELETE | /api/webhooks/{webhookId} | Lire, modifier, supprimer |
| POST | /api/webhooks/{webhookId}/rotate-secret | { webhook, newSecret, overlapMs } (Owner) |
| POST | /api/webhooks/{webhookId}/test | { delivery } |
| POST | /api/webhooks/{webhookId}/trigger | { event, payload } → { message, deliveryId } |
| GET | /api/webhooks/{webhookId}/deliveries | { data, total } ; filtres status, event, createdFrom, createdTo |
| POST | /api/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver | Remettre en file d’attente une livraison FAILED ou DEAD_LETTERED |
| GET, POST | /api/webhooks/{webhookId}/deliveries/replay-dead-letter | Compter, ou remettre en file d’attente, chaque lettre morte |
| GET | /api/webhooks/metrics, /api/webhooks/report | Statistiques de livraison (?webhookId=&days=) |
Corps de création : name, description, url, events, headers, eventFilters, tags, rateLimitPerMinute (de 1 à 100 000), ipAllowlist, format (json ou cloudevents).
| Refus | Signification |
|---|---|
403 WEBHOOKS_NOT_IN_PLAN | Votre offre ne comprend pas les webhooks |
409 ENDPOINT_DISABLED | Le point de terminaison est désactivé ; activez-le d’abord |
409 DELIVERY_NOT_REDELIVERABLE | La livraison est en attente ou a déjà réussi |
422 EVENT_FILTERED_OUT | Le filtre du point de terminaison écarterait l’exemple que vous avez déclenché |
422 | Un événement qu’aucun module de votre organisation ne propose |

