Neu: Die KI-Firewall überwacht die gesamte Plattform und erklärt jeden Vorfall in einfachen Worten. So funktioniert es

Webhooks

Signierte HTTP-Aufrufe empfangen, wenn sich Geräte, Alarme, Befehle, Firmware und Regeln ändern – Einrichtung, Signaturen, CloudEvents, Wiederholungsversuche, Tests und die Webhook-API.

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

  1. Öffnen Sie Webhooks und wählen Sie New Webhook.
  2. Geben Sie einen Name und optional eine Description ein („Wofür dient dieser Webhook?“).
  3. Geben Sie die URL ein. Sie muss HTTPS verwenden: „Die Webhook-URL muss eine gültige HTTPS-URL sein.“
  4. Wählen Sie unter Events mindestens ein Ereignis aus. Die Liste zeigt nur die Ereignisse der Module, die Ihre Organisation verwendet.
  5. 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-Length und X-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.
  6. 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:

HeaderWert
Content-Typeapplication/json (Standardformat) oder application/cloudevents+json; charset=utf-8
User-AgentHermetry-Webhooks/1.0
X-Webhook-EventDer Ereignisname, zum Beispiel device.disconnected
X-Webhook-DeliveryDie Zustell-ID. Sie ist bei jedem Wiederholungsversuch und jeder erneuten Zustellung derselben Zustellung gleich.
X-Webhook-TimestampUnix-Sekunden, zu denen dieser Versuch signiert wurde
X-Webhook-Signature-V2sha256= + HMAC-SHA256 von "<timestamp>.<body>" mit Ihrem Geheimnis. Verwenden Sie diese Variante.
X-Webhook-SignatureHMAC-SHA256 nur des Body. Ältere Form, für eine Übergangszeit beibehalten.
X-Webhook-Signature-Prev, X-Webhook-Signature-V2-PrevDasselbe mit dem vorherigen Geheimnis während einer Geheimnis-Rotation
X-Webhook-Manualtrue bei einem Ereignis, das ein Administrator manuell gesendet hat
X-Idempotency-KeyBei 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

EinstellungStandardBereich
Request Timeout (ms)15,0001.000 bis 120.000
Max Delivery Attempts (der erste mitgezählt)31 bis 10
Retry Backoff (ms): die Wartezeit vor Wiederholung 1, 2, …60000,300000,9000001 bis 9 Werte, jeweils 1.000 bis 86.400.000; danach der letzte Wert
Circuit Breaker Threshold: aufeinanderfolgende Fehler, bevor der Endpunkt abgeschaltet wird101 bis 100.000
Default Rate Limit (per minute): für Endpunkte ohne eigenes Limitunbegrenztleer 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 test und 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: true und X-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.

MethodePfadFunktion
GET/api/webhooks/eventsDie Ereignisse, die Sie abonnieren können
GET, POST/api/webhooksListe (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}/redeliverEine Zustellung mit Status FAILED oder DEAD_LETTERED erneut einreihen
GET, POST/api/webhooks/{webhookId}/deliveries/replay-dead-letterJeden Dead Letter zählen oder erneut einreihen
GET/api/webhooks/metrics, /api/webhooks/reportZustellungsstatistik (?webhookId=&days=)

Felder des Create-Body: name, description, url, events, headers, eventFilters, tags, rateLimitPerMinute (1 bis 100.000), ipAllowlist, format (json oder cloudevents).

AblehnungBedeutung
403 WEBHOOKS_NOT_IN_PLANIhr Tarif umfasst keine Webhooks
409 ENDPOINT_DISABLEDDer Endpunkt ist ausgeschaltet; schalten Sie ihn zuerst ein
409 DELIVERY_NOT_REDELIVERABLEDie Zustellung steht noch aus oder war bereits erfolgreich
422 EVENT_FILTERED_OUTDer Filter des Endpunkts würde das ausgelöste Beispiel verwerfen
422Ein Ereignis, das kein Modul Ihrer Organisation anbietet