Ugrás a fő tartalomhoz
Hasznos volt ez az oldal?

Webhookok

A webhookok lehetővé teszik, hogy a PrimeCal-on kívüli rendszerek automatikusan kiváltsák az automatizálási szabályaidat. Amikor egy külső szolgáltatás — egy foglalási platform, egy CRM, egy webáruház — JSON üzenetet küld a szabályod webhook URL-jére, a PrimeCal fogadja azt, és lefuttatja a szabályt.

Hogyan működnek a webhookok​

Minden automatizálási szabály, amely a webhook.incoming kiváltót használja, saját egyedi URL-t kap. Amikor egy harmadik féltől származó rendszer aláírt HTTP POST kérést küld erre az URL-re egy JSON törzzsel, a szabályod kiváltódik.

A folyamat:

  1. A külső rendszer POST kérést küld a webhook URL-edre
  2. A PrimeCal fogadja a payloadot, és naplózza
  3. A szabály feltételeit kiértékeli a payload adatai alapján
  4. Ha a feltételek illeszkednek (vagy nincs feltétel), a művelet lefut

A webhook URL megtalálása​

  1. Menj a Vezérlőpult → Automatizálás menübe
  2. Nyisd meg a szabályt, amit csatlakoztatni szeretnél (vagy hozz létre újat webhook.incoming kiváltóval)
  3. A szabály részletes nézetében nyisd meg a Webhook fület
  4. Másold ki az URL-t — így néz ki: 
    https://api.primecal.eu/api/automation/webhook/abc123xyz

Minden szabálynak más token van az URL-jében. Ez a token azonosítja a szabályodat, de önmagában nem elég a kiváltásához — lásd lentebb.

A kéréseket alá kell írni — egy egyszerű POST nem fog működni

Sok egyszerű webhook-fogadóval ellentétben a PrimeCal megköveteli, hogy minden bejövő kérés érvényes HMAC-SHA256 aláírást hordozzon, nem csak az URL tokent. Az aláírás nélküli kérés elutasításra kerül. Ez több beállítást igényel, mint egy egyszerű POST, de azt jelenti, hogy önmagában a token kiszivárgása nem használható a szabályod kiváltására.

Webhook kérés küldése​

A külső rendszerednek Content-Type: application/json fejléccel kell kérést küldenie, és két kötelező fejléccel: egy időbélyeggel és egy, a payloadodból és egy szabályonkénti titokból számított aláírással.

Példa payload:

{
  "event": "order.completed",
  "data": {
    "order_id": "12345",
    "customer": "John Doe",
    "total": 99.99,
    "status": "paid"
  }
}

A PrimeCal bármilyen érvényes JSON-struktúrát elfogad. A felső szintű forma rugalmas — használhatsz data, payload, body mezőt, vagy bármilyen beágyazást, amit szeretnél. Ami számít, hogy ugyanazokat az útvonalakat hivatkozd a feltételeidben pont-jelöléssel (pl. webhook.data.order_id).

Az aláíró titok (signing secret) megszerzése​

A webalkalmazás jelenleg nem mutatja közvetlenül a szabályod aláíró titkát. Szerezd meg (vagy forgasd) bejelentkezve, a következő hívással:

curl -X POST https://api.primecal.eu/api/automation/rules/YOUR_RULE_ID/webhook/rotate-secret \
  -H "Authorization: Bearer YOUR_JWT_OR_API_KEY"

Ez visszaad egy webhookSecret-et — mentsd el biztonságos helyre, mert nincs mód újra megtekinteni anélkül, hogy forgatnád (ami rövid türelmi idő után érvényteleníti a régit). A legtöbb integrátor ezt egyszer teszi meg, majd beégeti a titkot a küldő rendszerbe.

Az aláírás kiszámítása​

Minden kéréshez:

  1. timestamp = az aktuális Unix idő másodpercben.
  2. Építsd fel a "{timestamp}.{rawJsonBody}" karakterláncot.
  3. signature = HMAC-SHA256(webhookSecret, az a karakterlánc), hexadecimálisan.
  4. Küldd el az X-PrimeCal-Timestamp: {timestamp} és X-PrimeCal-Signature: {signature} fejléceket.

Az időbélyegnek a PrimeCal órájának 5 percén belül kell lennie, és minden aláírt kérés csak egyszer használható — ez megakadályozza, hogy régi, elfogott kéréseket később újra lejátszhassanak.

Teljes kérés/válasz példák (Node.js és curl) a Webhook API referenciában találhatók — ezt az oldalt add oda annak, aki a küldő oldalt implementálja.

Tesztelés curl-lal​

A kötelező aláírás miatt a teszteléshez a titok és egy kiszámított aláírás is kell, nem csak egy egyszerű POST. A leggyorsabb módja a tesztelésnek, ha az aláírást a helyszínen generálod:

SECRET="a webhookSecret, amit a rotate-secret-től kaptál"
BODY='{"event":"test","data":{"priority":"high","customer_id":"123"}}'
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"

Cseréld ki a YOUR_TOKEN-t a szabályod Webhook fülén található tokenre. Küldés után nézd meg a szabály History fülét a PrimeCal-ban, hogy megerősítsd, a kérés megérkezett és naplózva lett.

Payload adatok használata feltételekben​

Amint egy webhook megérkezik, megvizsgálhatod a tartalmát a feltételeken belül a webhook.data pont-jelöléssel:

  • webhook.data.order_id → az order_id mező a data alatt
  • webhook.data.customer → a customer mező a data alatt
  • webhook.data.status → a status mező a data alatt

Példa szabály: csak akkor cselekedj, ha a status egyenlő "paid"-del:

  • Feltétel mező: webhook.data.status
  • Operátor: equals
  • Érték: paid

Lásd: Smart Values a pont-jelölés és a beágyazott elérés teljes magyarázatáért.

Gyakorlati példa: foglalás megerősítése​

Egy foglalási platform webhookot küld a PrimeCal-nak, amikor valaki lefoglal egy medence-alkalmat. A payload így néz ki:

{
  "event": "booking.confirmed",
  "data": {
    "booking_id": "bk_001",
    "guest_name": "Sarah Connor",
    "slot": "2026-07-15T10:00:00",
    "type": "pool"
  }
}

Azt szeretnéd, hogy az összes bejövő medence-foglalás cián színt kapjon, hogy kiemelkedjen a naptárban.

Szabálybeállítás:

  1. Kiváltó: webhook.incoming
  2. Feltétel: webhook.data.type egyenlő pool
  3. Művelet: Esemény színének beállítása → Cián

Amikor a foglalási rendszer kiváltja a webhookot, a PrimeCal fogadja, ellenőrzi, hogy a type pool-e, és alkalmazza a cián színt a kapcsolódó eseményre.

URL token regenerálása vs. aláíró titok forgatása​

Ez két különböző érték, és a PrimeCal-nak két különböző művelete van rájuk:

  • Az URL token (a webhook URL-ben lévő rész) — regeneráld a szabály Webhook füléről, ha gyanítod, hogy maga az URL kiszivárgott. A régi URL azonnal leáll.
  • Az aláíró titok — forgasd az API-n keresztül (lásd fent), ha gyanítod, hogy a titok kiszivárgott, vagy óvintézkedésként rendszeresen. A régi titok rövid türelmi ideig még működik, hogy leállás nélkül frissíthesd a küldő rendszert, majd leáll.

Az egyik regenerálása nem érinti a másikat — azt forgasd, ami valójában kiszivárgott.

Webhook naplók ellenőrzése​

Minden webhook kérés — akár kiváltotta a műveletet, akár a feltételek kiszűrték — naplózva van a szabály audit-nyomvonalában.

  1. Nyisd meg a szabály részletes nézetét
  2. Menj a History fülre
  3. Minden bejegyzés mutatja az időbélyeget, a bejövő payloadot, mely feltételeket értékelte ki, és az eredményt

Ez az első hely, amit meg kell nézni, ha egy webhook nem tűnik működni.

Hibaelhárítás​

Ha a webhookod nem váltja ki a szabályt a várt módon, lásd az Automatizálások hibaelhárítása oldalt a teljes ellenőrzőlistáért. A leggyakoribb problémák:

  • 401 Unauthorized — hiányzó vagy érvénytelen X-PrimeCal-Signature/X-PrimeCal-Timestamp fejlécek, több mint 5 perccel eltérő időbélyeg, vagy rossz titok vagy rossz nyers törzs alapján számított aláírás. Ez soha nem jut el a History fülig, mivel a kérés elutasításra kerül, mielőtt a szabály lefutna — nézd meg a küldő rendszered saját naplóit a HTTP válaszért.
  • Rossz Content-Type fejléc (application/json-nak kell lennie)
  • Az URL-ben lévő token nem egyezik a szabály jelenlegi tokenjével
  • Egy feltétel kiszűri a kérést (nézd meg a History fület az okért — a 200-as válasz azt jelenti, hogy a kérést elfogadták és kiértékelték, nem azt, hogy illeszkedett)