Ein Webhook ist eine Adresse in Ihrem System, die Hermetry aufruft, wenn ein Ereignis eintritt. Verwenden Sie ihn, um ein Ticketsystem, ein ERP, einen Message Bus oder Ihren eigenen Dienst zu versorgen. Webhooks werden von Administratoren unter Webhooks (im Bereich Developer des Menüs) verwaltet. Das Senden von Webhooks erfordert einen Tarif, der sie enthält.
Webhook erstellen
- Öffnen Sie Webhooks und wählen Sie New Webhook.
- Geben Sie einen Name und optional eine Description ein („Wofür dient dieser Webhook?“).
- Geben Sie die URL ein. Sie muss HTTPS verwenden: „Die Webhook-URL muss eine gültige HTTPS-URL sein.“
- Wählen Sie unter Events mindestens ein Ereignis aus. Die Liste zeigt nur die Ereignisse der Module, die Ihre Organisation verwendet.
- Optional:
- Custom headers (optional): bis zu 20 Header, die bei jedem Aufruf gesendet werden, zum Beispiel ein Autorisierungstoken, das Ihr Empfänger prüft.
Content-Type,User-Agent,Host,Content-LengthundX-Webhook-*können nicht gesetzt werden. Werte sind einzeilig und höchstens 1.000 Zeichen lang. - Event filters (optional, advanced): liefert ein Ereignis nur dann, wenn seine Nutzlast übereinstimmt (siehe unten).
- Tags (optional, comma-separated): Bezeichnungen zur Organisation Ihrer Webhooks, bis zu 20.
- Rate limit (optional, deliveries/minute): leer bedeutet unbegrenzt.
- Custom headers (optional): bis zu 20 Header, die bei jedem Aufruf gesendet werden, zum Beispiel ein Autorisierungstoken, das Ihr Empfänger prüft.
- Speichern. Kopieren Sie das Signing secret jetzt: Es wird nur einmal angezeigt.
Alle Ereignisse der IoT-Module sind mit Beispiel-Nutzlasten in der Webhook event reference aufgeführt.
Event filters
Ein Ereignisfilter ist eine JSON-Zuordnung von einem Ereignis zu den Nutzlastfeldern, mit denen es übereinstimmen muss. Eine Zustellung wird übersprungen, wenn die Nutzlast nicht übereinstimmt. Ereignisse ohne Filter werden immer zugestellt.
{
"alarm.created": { "severity": "CRITICAL" },
"device.disconnected": { "profileId": "6f1c0a2e-0000-4000-8000-000000000001" }
}
Jeder Pfad benennt ein Feld von data des Ereignisses und kann mit Punkten geschrieben werden, zum Beispiel originator.type. Jedes aufgeführte Feld muss seinem Wert entsprechen (Zahlen und Text werden als Text verglichen, daher stimmt "2" mit 2 überein). Höchstens 50 Ereignisse können einen Filter haben.
So sieht eine Zustellung aus
Hermetry sendet ein POST mit diesen Headern:
| Header | Wert |
|---|---|
Content-Type | application/json (Standardformat) oder application/cloudevents+json; charset=utf-8 |
User-Agent | Hermetry-Webhooks/1.0 |
X-Webhook-Event | Der Ereignisname, zum Beispiel device.disconnected |
X-Webhook-Delivery | Die Zustell-ID. Sie ist bei jedem Wiederholungsversuch und jeder erneuten Zustellung derselben Zustellung gleich. |
X-Webhook-Timestamp | Unix-Sekunden, zu denen dieser Versuch signiert wurde |
X-Webhook-Signature-V2 | sha256= + HMAC-SHA256 von "<timestamp>.<body>" mit Ihrem Geheimnis. Verwenden Sie diese Variante. |
X-Webhook-Signature | HMAC-SHA256 nur des Body. Ältere Form, für eine Übergangszeit beibehalten. |
X-Webhook-Signature-Prev, X-Webhook-Signature-V2-Prev | Dasselbe mit dem vorherigen Geheimnis während einer Geheimnis-Rotation |
X-Webhook-Manual | true bei einem Ereignis, das ein Administrator manuell gesendet hat |
X-Idempotency-Key | Bei Nachrichten, die ein Flow über seinen Webhook-Block sendet |
Beim Standardformat ist der Body ein Envelope:
{
"webhookId": "…",
"tenantId": "…",
"event": "device.disconnected",
"createdAt": "2026-11-03T12:00:30.000Z",
"data": { "deviceId": "…", "name": "router-17", "reason": "timeout", "…": "…" }
}
Ein Ereignis, das ein Administrator manuell gesendet hat, enthält außerdem "manual": true. Antworten Sie innerhalb des Timeouts mit einem beliebigen 2xx-Status. Die ersten 4 KB des Antwort-Body werden im Zustellprotokoll gespeichert.
CloudEvents-Format
Ein Endpunkt kann stattdessen CloudEvents 1.0 im Structured Mode empfangen. Setzen Sie "format": "cloudevents" über die API (POST oder PATCH /api/webhooks/..., siehe unten). "json" ist der Standard.
{
"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 enthält genau das, was das Standardformat unter data enthält. id ist bei jedem Wiederholungsversuch und jeder erneuten Zustellung gleich, daher sollten Sie anhand von source und id deduplizieren. Die Signatur-Header sind in beiden Formaten gleich. Batch- und Binary-Modus werden nicht angeboten.
Signatur prüfen
Prüfen Sie gegen den unveränderten Body, bevor Sie ihn parsen, und weisen Sie alte Zeitstempel ab.
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);
}
Während einer Geheimnis-Rotation akzeptieren Sie einen Aufruf, wenn entweder X-Webhook-Signature-V2 oder X-Webhook-Signature-V2-Prev übereinstimmt.
Zustellung, Wiederholungen und Dead Letters
| Einstellung | Standard | Bereich |
|---|---|---|
| Request Timeout (ms) | 15,000 | 1.000 bis 120.000 |
| Max Delivery Attempts (der erste mitgezählt) | 3 | 1 bis 10 |
| Retry Backoff (ms): die Wartezeit vor Wiederholung 1, 2, … | 60000,300000,900000 | 1 bis 9 Werte, jeweils 1.000 bis 86.400.000; danach der letzte Wert |
| Circuit Breaker Threshold: aufeinanderfolgende Fehler, bevor der Endpunkt abgeschaltet wird | 10 | 1 bis 100.000 |
| Default Rate Limit (per minute): für Endpunkte ohne eigenes Limit | unbegrenzt | leer oder 0 = unbegrenzt |
Legen Sie diese unter Webhooks > Einstellungen (Zahnrad-Schaltfläche) fest. Eine Zustellung hat einen der Status PENDING, SUCCESS, FAILED (wird wiederholt) oder DEAD_LETTERED (alle Versuche verbraucht).
- Jede Zustellung wird mit Status, Versuchen, Antwortcode, Fehler, Dauer und nächstem Wiederholungszeitpunkt protokolliert.
- Ein Endpunkt über seinem Ratenlimit erhält seine Zustellungen etwa 60 Sekunden später; nichts geht verloren.
- Nach dem Schwellenwert aufeinanderfolgender Fehler wird der Endpunkt abgeschaltet und als automatisch deaktiviert angezeigt. Eingereihte Wiederholungen werden gestoppt. Schalten Sie ihn wieder ein, um den Zähler zurückzusetzen, und stellen Sie dann fehlgeschlagene Zustellungen erneut zu oder spielen Sie sie ab.
- Zustellungen erfolgen mindestens einmal. Deduplizieren Sie anhand von
X-Webhook-Delivery(oder der CloudEvents-id). - Ereignisse kommen nicht garantiert in der richtigen Reihenfolge an. Verwenden Sie die Zeitangaben in der Nutzlast.
Ereignisse zu Geräteverbindung und Geräteänderung haben eine eigene Volumenbegrenzung: standardmäßig höchstens 600 jeder Art pro Organisation und Minute. Siehe die Webhook event reference.
Geheimnis rotieren
Wählen Sie Rotate signing secret (Rolle Owner). Das neue Geheimnis wird einmal angezeigt. Das vorherige Geheimnis bleibt 48 Stunden gültig, und während dieser Zeit trägt jeder Aufruf beide Signaturen. Wird während dieses Fensters erneut rotiert, ersetzt dies nur das aktuelle Geheimnis; das vorherige behält sein Enddatum.
Test
Über die Zeilenaktionen eines Webhooks oder über seine Seite:
- Send test event sendet sofort ein Ereignis namens
testund zeigt das Ergebnis an („Test delivered — HTTP 200 in 85 ms“). Ein Test zählt nie zum Circuit Breaker. - Trigger event… sendet ein echtes, signiertes Ereignis Ihrer Wahl mit einer Beispiel-Nutzlast (JSON-Objekt, höchstens 64 KB), markiert mit
manual: trueundX-Webhook-Manual: true. Es berücksichtigt den Ereignisfilter des Endpunkts: Ein Beispiel, das der Filter verwerfen würde, wird abgelehnt. - View deliveries listet die Zustellungen auf; eine fehlgeschlagene oder als Dead Letter markierte Zustellung kann erneut zugestellt werden, und alle Dead Letters können auf einmal erneut abgespielt werden.
Netzwerkregeln
Webhook-Adressen müssen öffentliche HTTPS-Adressen sein. Private, Loopback-, Link-Local- und Cloud-Metadaten-Adressen werden beim Speichern und erneut bei jedem Aufruf abgelehnt, und Weiterleitungen werden nicht verfolgt. Für ein absichtlich internes Ziel kann ein Administrator über die API einen expliziten ipAllowlist (bis zu 50 Adressen oder CIDR-Bereiche) für den Webhook setzen.
Die Webhook-API
Pfade liegen unter /tenant/<tenantId>. Alle erfordern die Berechtigungen eines Administrators.
| Methode | Pfad | Funktion |
|---|---|---|
| GET | /api/webhooks/events | Die Ereignisse, die Sie abonnieren können |
| GET, POST | /api/webhooks | Liste (page ab 1, pageSize, search, sort, isActive, autoDisabled); Erstellen: 201 { webhook, secret } |
| GET, PATCH, DELETE | /api/webhooks/{webhookId} | Lesen, ändern, löschen |
| 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 }; Filter status, event, createdFrom, createdTo |
| POST | /api/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver | Eine Zustellung mit Status FAILED oder DEAD_LETTERED erneut einreihen |
| GET, POST | /api/webhooks/{webhookId}/deliveries/replay-dead-letter | Jeden Dead Letter zählen oder erneut einreihen |
| GET | /api/webhooks/metrics, /api/webhooks/report | Zustellungsstatistik (?webhookId=&days=) |
Felder des Create-Body: name, description, url, events, headers, eventFilters, tags, rateLimitPerMinute (1 bis 100.000), ipAllowlist, format (json oder cloudevents).
| Ablehnung | Bedeutung |
|---|---|
403 WEBHOOKS_NOT_IN_PLAN | Ihr Tarif umfasst keine Webhooks |
409 ENDPOINT_DISABLED | Der Endpunkt ist ausgeschaltet; schalten Sie ihn zuerst ein |
409 DELIVERY_NOT_REDELIVERABLE | Die Zustellung steht noch aus oder war bereits erfolgreich |
422 EVENT_FILTERED_OUT | Der Filter des Endpunkts würde das ausgelöste Beispiel verwerfen |
422 | Ein Ereignis, das kein Modul Ihrer Organisation anbietet |

