Webhookovi – Hermetry

Webhook je adres u vašem sustavu koji Hermetry poziva kad se dogodi događaj. Upotrijebite ga za slanje podataka u sustav za tikete, ERP, message bus ili vlastitu uslugu. Webhookovima upravljaju administratori na Webhooks (u dijelu Developer izbornika). Slanje webhookova zahtijeva paket koji ih uključuje.

Stvaranje webhooka

Otvorite Webhooks i odaberite New Webhook.
Unesite Name i, po želji, Description (“Za što je ovaj webhook?”).
Unesite URL. Mora biti HTTPS: “Webhook URL mora biti valjani HTTPS URL.”
Pod Events odaberite barem jedan događaj. Popis prikazuje samo događaje modula koje vaša organizacija koristi.
Po želji:
- Custom headers (optional): do 20 zaglavlja poslanih uz svaki poziv, na primjer autorizacijski token koji vaš primatelj provjerava. Content-Type, User-Agent, Host, Content-Length i X-Webhook-* ne mogu se postaviti. Vrijednosti su u jednom retku, najviše 1.000 znakova.
- Event filters (optional, advanced): isporuči događaj samo kad se njegov payload podudara (vidi dolje).
- Tags (optional, comma-separated): oznake za organiziranje webhookova, do 20.
- Rate limit (optional, deliveries/minute): prazno znači bez ograničenja.
Spremite. Odmah kopirajte Signing secret: prikazuje se samo jednom.

Svi događaji IoT modula navedeni su s primjerima payloada u Webhook event reference.

Filteri događaja

Filter događaja je JSON mapa od događaja na polja payloada koja moraju odgovarati. Isporuka se preskače kad payload ne odgovara. Događaji bez filtera uvijek se isporučuju.

{
  "alarm.created": { "severity": "CRITICAL" },
  "device.disconnected": { "profileId": "6f1c0a2e-0000-4000-8000-000000000001" }
}

Svaka putanja imenuje polje data događaja i može biti s točkama, na primjer originator.type. Svako navedeno polje mora biti jednako svojoj vrijednosti (brojevi i tekst uspoređuju se kao tekst, pa "2" odgovara 2). Najviše 50 događaja može imati filter.

Kako izgleda isporuka

Hermetry šalje POST s ovim zaglavljima:

Zaglavlje	Vrijednost
`Content-Type`	`application/json` (zadani format) ili `application/cloudevents+json; charset=utf-8`
`User-Agent`	`Hermetry-Webhooks/1.0`
`X-Webhook-Event`	Naziv događaja, na primjer `device.disconnected`
`X-Webhook-Delivery`	ID isporuke. Isti je pri svakom ponovnom pokušaju i ponovnoj isporuci jedne isporuke.
`X-Webhook-Timestamp`	Unix sekunde kad je ovaj pokušaj potpisan
`X-Webhook-Signature-V2`	`sha256=` + HMAC-SHA256 od `"<timestamp>.<body>"` s vašom tajnom. Koristite ovaj.
`X-Webhook-Signature`	HMAC-SHA256 samo tijela. Stariji oblik, zadržan za prijelazno razdoblje.
`X-Webhook-Signature-Prev`, `X-Webhook-Signature-V2-Prev`	Isto s prethodnom tajnom, tijekom rotacije tajne
`X-Webhook-Manual`	`true` za događaj koji je administrator ručno poslao
`X-Idempotency-Key`	Za poruke koje tok šalje preko svog webhook bloka

Uz zadani format, tijelo je omotnica:

{
  "webhookId": "…",
  "tenantId": "…",
  "event": "device.disconnected",
  "createdAt": "2026-11-03T12:00:30.000Z",
  "data": { "deviceId": "…", "name": "router-17", "reason": "timeout", "…": "…" }
}

Događaj koji je administrator ručno poslao također ima "manual": true. Odgovorite bilo kojim 2xx statusom unutar vremenskog ograničenja. Prvih 4 KB tijela vašeg odgovora čuvaju se u dnevniku isporuka.

CloudEvents format

Krajnja točka može umjesto toga primati CloudEvents 1.0 u strukturiranom načinu. Obrazac webhooka još nema izbor formata: postavite "format": "cloudevents" putem API-ja (POST ili PATCH /api/webhooks/..., vidi dolje). "json" je zadani.

{
  "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 sadrži točno ono što zadani format sadrži pod data. id je isti pri svakom ponovnom pokušaju i ponovnoj isporuci, pa deduplicirajte prema source i id. Zaglavlja potpisa su ista u oba formata. Batch i binarni načini nisu ponuđeni.

Provjera potpisa

Provjerite nad sirovim tijelom, prije parsiranja, i odbacite stare vremenske oznake.

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);
}

Tijekom rotacije tajne prihvatite poziv kad se podudara X-Webhook-Signature-V2 ili X-Webhook-Signature-V2-Prev.

Isporuka, ponovni pokušaji i nedostavljive poruke

Postavka	Zadano	Raspon
Request Timeout (ms)	15,000	1.000 do 120.000
Max Delivery Attempts (uključujući prvi)	3	1 do 10
Retry Backoff (ms): čekanje prije ponovnog pokušaja 1, 2, …	`60000,300000,900000`	1 do 9 vrijednosti, svaka od 1.000 do 86.400.000; nakon popisa, posljednja vrijednost
Circuit Breaker Threshold: uzastopni neuspjesi prije isključivanja krajnje točke	10	1 do 100.000
Default Rate Limit (per minute): za krajnje točke bez vlastitog	bez ograničenja	prazno ili 0 = bez ograničenja

Postavite ih na Webhooks > postavke (gumb zupčanika). Isporuka je jedna od: PENDING, SUCCESS, FAILED (bit će ponovno pokušana) ili DEAD_LETTERED (iskorišteni su svi pokušaji).

Svaka isporuka bilježi se sa statusom, pokušajima, kodom odgovora, greškom, trajanjem i vremenom sljedećeg ponovnog pokušaja.
Krajnja točka iznad svog ograničenja brzine dobiva isporuke oko 60 sekundi kasnije; ništa se ne odbacuje.
Nakon praga uzastopnih neuspjeha krajnja točka se isključuje i prikazuje se kao auto-disabled. Čekajući ponovni pokušaji se zaustavljaju. Ponovno je uključite kako biste resetirali brojač, zatim ponovno isporučite ili replayajte ono što nije uspjelo.
Isporuke su barem jednom. Deduplicirajte prema X-Webhook-Delivery (ili CloudEvents id).
Nije zajamčeno da će događaji stići redom. Koristite vremena u payloadu.

Događaji o vezi uređaja i promjenama uređaja imaju vlastiti ograničnik obujma: zadano najviše 600 svake vrste po organizaciji u minuti. Vidi Webhook event reference.

Rotirajte tajnu

Odaberite Rotate signing secret (uloga Owner). Nova tajna prikazuje se jednom. Prethodna tajna ostaje valjana 48 sati, a tijekom tog vremena svaki poziv nosi oba potpisa. Ponovna rotacija dok je prozor otvoren zamjenjuje samo trenutnu tajnu; prethodna zadržava svoj datum završetka.

Testiranje

Iz radnih akcija retka webhooka ili s njegove stranice:

Send test event odmah šalje događaj nazvan test i prikazuje rezultat (“Test isporučen — HTTP 200 za 85 ms”). Test se nikad ne računa prema circuit breakeru.
Trigger event… šalje stvarni, potpisani događaj po vašem izboru s primjerom payloada (JSON objekt, najviše 64 KB), označen s manual: true i X-Webhook-Manual: true. Poštuje filter događaja krajnje točke: uzorak koji bi filter odbacio bit će odbijen.
View deliveries prikazuje isporuke; neuspjela ili nedostavljiva isporuka može se ponovno isporučiti, a sve nedostavljive poruke mogu se odjednom replayati.

Mrežna pravila

Adrese webhookova moraju biti javne HTTPS adrese. Privatne, loopback, link-local i adrese cloud metapodataka odbijaju se pri spremanju i ponovno pri svakom pozivu, a preusmjeravanja se ne slijede. Za namjerno interni cilj administrator može na webhooku putem API-ja postaviti eksplicitni ipAllowlist (do 50 adresa ili CIDR raspona).

API za webhookove

Putanje su pod /tenant/<tenantId>. Sve zahtijevaju dozvole administratora.

Metoda	Putanja	Radi
GET	`/api/webhooks/events`	Događaji na koje se možete pretplatiti
GET, POST	`/api/webhooks`	Popis (`page` od 1, `pageSize`, `search`, `sort`, `isActive`, `autoDisabled`); stvaranje: `201 { webhook, secret }`
GET, PATCH, DELETE	`/api/webhooks/{webhookId}`	Čitanje, izmjena, brisanje
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 }`; filteri `status`, `event`, `createdFrom`, `createdTo`
POST	`/api/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver`	Ponovno stavlja u red FAILED ili DEAD_LETTERED isporuku
GET, POST	`/api/webhooks/{webhookId}/deliveries/replay-dead-letter`	Broji ili ponovno stavlja u red svaku nedostavljivu poruku
GET	`/api/webhooks/metrics`, `/api/webhooks/report`	Statistika isporuka (`?webhookId=&days=`)

Tijelo za stvaranje: name, description, url, events, headers, eventFilters, tags, rateLimitPerMinute (1 do 100.000), ipAllowlist, format (json ili cloudevents).

Odbijanje	Značenje
`403` `WEBHOOKS_NOT_IN_PLAN`	Vaš paket ne uključuje webhookove
`409` `ENDPOINT_DISABLED`	Krajnja točka je isključena; prvo je uključite
`409` `DELIVERY_NOT_REDELIVERABLE`	Isporuka je na čekanju ili je već uspjela
`422` `EVENT_FILTERED_OUT`	Filter krajnje točke odbacio bi uzorak koji ste pokrenuli
`422`	Događaj koji nijedan modul vaše organizacije ne nudi