# Webhookok

> Kimenő eseményértesítések beállítása, tesztküldés, aláírt JSON-kérések fogadása és a Komashi webhook-újrapróbálkozásainak kezelése.

Canonical: https://komashi.com/docs/hu/provider/Settings/11webhooks/
Language: hu

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.

Video (English narration): [Webhookok](https://www.youtube.com/watch?v=a_2yS5qOMaQ)

[![Webhooklista a végponttal, eseményfeliratkozásokkal és a Webhook tesztelése művelettel](https://komashi.com/docs/assets/images/integrations-webhooks.png)](/assets/images/integrations-webhooks.png)

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:

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

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

```json
{
  "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.

```js


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ó](https://komashi.com/docs/hu/provider/Developers/api-integration/index.md), [API-kulcsok](https://komashi.com/docs/hu/provider/Settings/10api/index.md).