Webhook API

Ez a technikai referencia a PrimeCal bejövő webhook-fogadójához — a végponthoz, amit egy külső rendszer hív, hogy kiváltson egy webhook.incoming automatizálási szabályt. Termékszintű bemutatóért lásd a Webhookok oldalt a Felhasználói kézikönyvben.

A kéréseket HMAC-kel alá kell írni — nincs aláíratlan mód

Minden hívás ehhez a végponthoz HMAC-SHA256 aláírással kerül ellenőrzésre. Nincs mód ezt szabályonként kikapcsolni, és egy aláíratlan kérés kategorikusan elutasításra kerül. Tervezz az aláírással a kezdetektől; egy egyszerű curl -d '{...}' POST elbukik.

Végpont

POST https://api.primecal.eu/api/automation/webhook/{token}
GET  https://api.primecal.eu/api/automation/webhook/{token}

A {token} szabályonként egyedi (webhookToken), megtalálható a szabály Webhook fülén az alkalmazásban, és onnan regenerálható.

• POST — küldd el a payloadodat JSON törzsként (Content-Type: application/json).
• GET — olyan hívóknak, akik nem tudnak POST törzset küldeni (IoT gombok, böngészőben kiváltott linkek). Ehelyett a lekérdezési karakterlánc paraméterei válnak payloaddá.

Mindkét változathoz ugyanaz az aláírás szükséges.

Az aláíró titok megszerzése

Minden szabálynak van egy webhookSecret-je, amely automatikusan generálódik a szabály létrehozásakor. A webalkalmazás jelenleg nem jeleníti meg — az egyetlen módja a lekérésének vagy forgatásának ez a végpont:

POST /api/automation/rules/{id}/webhook/rotate-secret

A szabály tulajdonosaként hitelesítve (normál JWT auth, nem a webhook token). Válasz:

{ "webhookSecret": "<új 128 karakteres hexadecimális titok>", "graceUntil": "2026-09-26T12:00:00.000Z" }

Ennek hívása forgatja a titkot — az előző titok a graceUntil-ig (alapértelmezetten 1 óráig) még működik, azután leáll. Nincs csak-olvasható "mutasd a jelenlegi titkot" hívás; ha elvesztetted a titkot, a forgatás az egyetlen visszaállítási mód.

Kérés aláírása

1. Időbélyeg — az aktuális Unix idő másodpercben, karakterláncként.
2. Aláírt payload — "{timestamp}.{rawRequestBody}" (a pontos byte-ok, amiket küldesz, nem egy újraszerializált verzió — GET kéréseknél üres karakterláncot használj a törzs helyett).
3. Aláírás — HMAC-SHA256(webhookSecret, aláírtPayload), hexadecimálisan kódolva.

Küldd el mindkettőt fejlécként:

Fejléc	Érték
X-PrimeCal-Timestamp	A fent használt Unix időbélyeg (másodperc)
X-PrimeCal-Signature	A hexadecimális aláírás, opcionálisan sha256= előtaggal

(Az X-Webhook-Signature/X-Webhook-Timestamp és az X-Hub-Signature-256 szintén elfogadott, a gyakori webhook-küldő konvenciókkal való kompatibilitáshoz.)

Példa (Node.js)

const crypto = require('crypto');

const secret = 'the webhookSecret from rotate-secret';
const body = JSON.stringify({ event: 'order.completed', data: { order_id: '12345' } });
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto
  .createHmac('sha256', secret)
  .update(`${timestamp}.${body}`)
  .digest('hex');

await fetch('https://api.primecal.eu/api/automation/webhook/YOUR_TOKEN', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-PrimeCal-Timestamp': timestamp,
    'X-PrimeCal-Signature': signature,
  },
  body,
});

Példa (curl, előre kiszámítva)

SECRET="the webhookSecret from rotate-secret"
BODY='{"event":"order.completed","data":{"order_id":"12345"}}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')

curl -X POST "https://api.primecal.eu/api/automation/webhook/YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-PrimeCal-Timestamp: $TS" \
  -H "X-PrimeCal-Signature: $SIG" \
  -d "$BODY"

Időbélyeg-tolerancia és visszajátszás elleni védelem

• Az időbélyegnek a szerver órájának 5 percén belül kell lennie (WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS, alapértelmezett 300). Az ablakon kívül a kérés elutasításra kerül — ez azt is jelenti, hogy nem játszhatsz vissza egy régi, elfogott kérést, miután az ablak bezárult.
• Minden (token, signature, timestamp) kombináció csak egyszer használható. Egy byte-azonos újrapróbálkozás ugyanazzal az aláírt kéréssel visszajátszásként elutasításra kerül.

Forgatás leállás nélkül

A rotate-secret új titkot ad az új kéréseidnek, miközben a régi még ellenőrzésre kerül a graceUntil-ig (alapértelmezetten 1 óra). Frissítsd a külső rendszered tárolt titkát azon az ablakon belül; utólag nincs mód meghosszabbítani — forgasd újra, ha több időre van szükséged.

Sebességkorlátok

A webhook hívások szabályonként sebességkorlátozottak: alapértelmezetten 60 kérés/60 másodperces ablak (AUTOMATION_WEBHOOK_MAX_PER_WINDOW / AUTOMATION_WEBHOOK_WINDOW_MS), függetlenül az API sebességkorlátok oldalon leírt általános API korlátoktól. Ennek túllépése egy hibát ad vissza, megnevezve az újrapróbálkozási késleltetést.

Opcionális: korlátozás forrás IP szerint

Egy szabály beállítható IP engedélyezőlistával (triggerConfig), hogy csak konkrét forrás IP-ktől érkező kérések legyenek elfogadva, az aláírás-ellenőrzés mellett. Ez az Automatizálás API segítségével állítható be, a szabályépítő felületén jelenleg nincs kitéve.

Válaszok

Állapot	Jelentés
200	{ "success": true, "ruleId": <id>, "message": "Webhook processed successfully" }
400	Hibásan formázott aláírás, vagy a szabály nem webhook.incoming szabály, vagy a szabály le van tiltva
401	Hiányzó/érvénytelen aláírás, tűréshatáron kívüli időbélyeg, vagy visszajátszott kérés
403	A szabálynak egyáltalán nincs webhookSecret-je (normál módon létrehozott szabálynál nem fordulhat elő)
404	A token nem egyezik egyetlen szabállyal sem
429	Sebességkorlát túllépve

A 200-as azt jelenti, hogy a kérést elfogadták és kiértékelték — nem azt, hogy a szabály feltételei illeszkedtek. Nézd meg a szabály audit naplóját (Automatizálás API), hogy lásd, valóban lefutott-e a művelet.

Kapcsolódók

• Webhookok (Felhasználói kézikönyv) — payload forma, feltételek, gyakorlati példák
• Automatizálás API — szabály CRUD, audit naplók, token regenerálás
• API sebességkorlátok