Webhookok

A webhookok JSON-értesítést küldenek a saját szerveredre a kiválasztott Komashi-eseményekről. Az aktuális szolgáltatónál nyisd meg a Vezérlőközpont → Integráció → Webhookok oldalt.

A támogatott beállításokat az alább felsorolt, kiválasztható események mutatják. Attól, hogy egy fizetési vagy számlaadat elérhető az API-ban, még nem feltétlenül tartozik hozzá általános fizetési vagy számla-webhookesemény.

Új webhook létrehozása

1. Készíts nyilvánosan elérhető fogadóvégpontot, amely JSON POST kérést fogad.
2. Kattints az Új webhook gombra.
3. Add meg a végpont URL-jét, például https://your-app.example/integrations/komashi.
4. Jelölj ki legalább egy eseményt. Az Összes kijelölése és Kijelölések megszüntetése az űrlap eseményválasztását módosítja.
5. Kattints a Mentés gombra.

Érvényes HTTP- vagy HTTPS-címet adj meg, amelyet a Komashi kiszolgálója elér. A localhost a küldő gépre mutat, nem a saját fejlesztői gépedre. Ugyanannál a szolgáltatónál ugyanarra a végpont URL-re nem vehető fel még egy webhook.

A listában a végpont, a kiválasztott események, a létrehozás ideje és a műveletek láthatók. A ceruza ikonnal módosíthatod az eseményválasztást, majd menthetsz. A szerkesztőablak a meglévő célcímet mutatja; új célponthoz hozz létre új webhookot, ellenőrizd a kézbesítést, majd vezesd ki a régit.

A törlés az adott beállítás jövőbeli kézbesítéseit állítja le. A fogadó rendszerben korábban feldolgozott változásokat nem vonja vissza.

Elérhető események

Csoport	Eseménynevek
Ügyfelek	customers.create, customers.update, customers.delete
Kapcsolattartók	contact.create, contact.update, contact.delete
Szolgáltatások	services.create, services.update, services.delete
Szolgáltatáscsomagok	service.plan.create, service.plan.update, service.plan.delete
Időszakok	service.period.create, service.period.update, service.period.delete
Árak	service.price.create, service.price.update, service.price.delete
Kiegészítők	service.addon.create, service.addon.update, service.addon.delete
Kiegészítőopciók	service.addon.option.create, service.addon.option.update, service.addon.option.delete
Előfizetési csomagok	subscription.plans.create, subscription.plans.update, subscription.plans.delete, subscription.plan.preview.link
Előfizetések	subscription.create, subscription.update, subscription.delete

Az eseménynevek pontos karakterláncok; az egyes és többes szám közötti különbséget is tartsd meg. Egy végpontra csak a hozzá kijelölt események érkeznek.

Teszt webhook küldése

A Webhook tesztelése művelet akkor jelenik meg, ha már legalább egy webhookot elmentettél egy nem demó szolgáltatónál.

1. Kattints a Webhook tesztelése gombra.
2. Add meg a saját kezelésedben álló Teszt URL értékét.
3. Válaszd ki a küldendő Példaeseményt.
4. Kattints a Teszt webhook küldése gombra.
5. Nézd meg a beérkezett kérést a saját szervereden, és a Komashi sikeres vagy sikertelen küldést jelző értesítését.

A teszt kitalált mintaadatokat használ; nem hoz létre és nem módosít Komashi-rekordokat. Egyetlen tesztkérést küld, az éles események sorba állított újrapróbálkozásaitól külön. Percenként legfeljebb 10 tesztküldés engedélyezett.

A jelenlegi tesztküldő az első elmentett webhook aláírási titkát használja. Több webhooknál ne feltételezd, hogy a tesztablakba írt URL-hez tartozó titokkal készül az aláírás.

A demó szolgáltatók nem küldenek kimenő webhookokat, és a szokásos módosítási, illetve tesztműveletek sem érhetők el náluk. Egy demóképernyőn szereplő előre feltöltött beállítás nem jelent tényleges kézbesítést.

A kérés formátuma

A kézbesítés az alábbi fejléceket tartalmazza:

Content-Type: application/json
X-Webhook-Event: customers.update
X-Signature: <hex-encoded HMAC-SHA256>

A JSON-boríték három mezője:

{
  "event": "customers.update",
  "timestamp": "2026-10-22T10:00:00+00:00",
  "data": {}
}

A data az eseményspecifikus erőforrásadatokat tartalmazza. Mezői eseményenként eltérnek; a fenti példa szándékosan nem sorol fel erőforrásmezőket. A tesztküldés mintaadatait ne tekintsd az összes valós esemény teljes sémájának. Ha a folyamatodnak a mérvadó aktuális állapot kell, kérdezd le az erőforrást az API-n.

Az aláírás ellenőrzése

A Komashi a JSON-törzset HMAC-SHA256 algoritmussal, a webhook saját titkával írja alá. Az ellenőrzést az eredeti kérésbájtokon végezd, a JSON feldolgozása vagy újraszerializálása előtt. Az aláírás kisbetűs hexadecimális érték, sha256= előtag nélkül.

A jelenlegi Webhookok oldalon nincs a generált titok kimásolására vagy megjelenítésére szolgáló vezérlő. Az alábbi példához a megfelelő titoknak biztonságos módon rendelkezésre kell állnia a fogadó rendszerben; az API-kulcs nem helyettesíti.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyKomashiWebhook(rawBody, signature, secret) {
  if (!secret || !/^[a-f0-9]{64}$/.test(signature ?? '')) return false;
  const expected = createHmac('sha256', secret).update(rawBody).digest();
  const received = Buffer.from(signature, 'hex');
  return received.length === expected.length && timingSafeEqual(received, expected);
}

A függvénynek a HTTP-keretrendszer eredeti kérésbufferét add át. Sikertelen aláírás-ellenőrzésnél az eseményt feldolgozás előtt utasítsd el.

Kézbesítés és újrapróbálkozás

A valódi események értesítései az adatbázis-tranzakció véglegesítése után kerülnek feldolgozási sorba. Ezért a kézbesítés késhet az üzleti művelethez képest.

• A kézbesítés legfeljebb négy alkalommal próbálkozik, 10, 60 és 300 másodperces újrapróbálkozási késleltetéssel.
• A kapcsolódási időkorlát 3 másodperc, a kérés időkorlátja 10 másodperc.
• Az esemény átvétele után mielőbb adj sikeres 2xx választ. A hosszabb feldolgozást a saját rendszeredben aszinkron módon végezd.
• Kapcsolati hiba, időtúllépés vagy sikertelen HTTP-válasz újrapróbálkozást eredményezhet. Duplikáció akkor is előfordulhat, ha az első kérést feldolgoztad, de a válasz elveszett.

A törzs nem tartalmaz általános kézbesítési azonosítót, és a sorrendre sincs garancia. A feldolgozás legyen idempotens, az adott eseményhez megfelelő azonosítók és állapot alapján. Az időbélyeg és az aláírás a próbálkozások között változhat, így önmagában egyik sem megbízható duplikációszűrő kulcs.

Hibaelhárítás

Probléma	Mit ellenőrizz?
Nem érkezik értesítés	A szolgáltató, az elmentett végpont, a pontosan kijelölt esemény és a demóállapot.
Nincs tesztgomb	Előbb ments el egy webhookot, és ne demó szolgáltatót használj.
A cím nem menthető	Nyilvánosan elérhető, az URL-ellenőrzés által elfogadott célpont szükséges.
Hibás aláírás	A megfelelő titok, eredeti kérésbájtok, hexadecimális formátum és a tesztküldő titokválasztása.
Ismételten érkezik ugyanaz	Adj gyors választ, és gondoskodj idempotens feldolgozásról.
Más az aktuális állapot	Olvasd ki az erőforrást REST API-val; az értesítés később is érkezhet a változásnál.

Kapcsolódó útmutatók: REST API-integráció, API-kulcsok.