Webhookok

A webhookkal a Lexo eseményei (új beszélgetés, új üzenet, lezárt beszélgetés, új lead, időpontfoglalás) automatikusan eljutnak a saját rendszeredbe. Minden esemény egy JSON törzsű HTTP POST kérés a megadott címre.

Mi az a webhook?

A webhook egy visszahívás: amikor a Lexóban történik valami, a rendszer azonnal kérést küld az általad megadott címre. Nem kell folyamatosan lekérdezned semmit, az adat magától megérkezik.

Webhook beállítása

A webhookokat a Beállítások → Integrációk oldalon, a Webhookok részben kezeled. Az Új webhook gombbal ezeket adod meg:

• Név: hogy később felismerd (pl. „Új leadek a CRM-be”).
• Cím: a végpontod. Csak https:// kezdetű cím adható meg.
• Események: egy vagy több a lenti listából.
• Újrapróbálkozás, ha a cím nem válaszol: alapból be van kapcsolva, legfeljebb 3 újrapróbálkozással; ez 1 és 10 között állítható.
• Titkos kulcs az értesítések aláírásához: alapból be van kapcsolva. A kulcsot a Lexo hozza létre (32 bájt, hexadecimálisan), és létrehozás után egyszer mutatja meg. Másold ki és tárold biztonságos helyen: később nem jeleníthető meg újra.

Az itt létrehozott webhook a fiókod összes chatbotjára vonatkozik. A listában minden webhooknál látod, hány kézbesítés történt és ebből hány volt sikertelen, mikor ment ki utoljára sikeresen értesítés, és mi volt az utolsó hiba. A sor menüjéből szerkesztheted, kikapcsolhatod vagy törölheted a webhookot, a Teszt küldése pedig azonnal küld egy test eseményt a címre.

Eseménytípusok

Kérés és payload

Minden kérés ezekkel a fejlécekkel érkezik:

A törzs minden eseménynél ugyanabban a burokban érkezik:

{
  "event": "lead.captured",
  "timestamp": "2026-10-11T14:30:00.000Z",
  "chatbot_id": "8f1c…",
  "data": {
    "conversation_id": "3b7e…",
    "email": "kovacs.peter@example.com",
    "name": "Kovács Péter",
    "phone": "+36 30 123 4567"
  }
}

A data mező tartalma eseményenként:

• conversation.created: conversation_id, visitor_id, valamint visitor_email és visitor_name, ha ismertek.
• conversation.message: conversation_id, message_id, is_user (true a látogató, false az AI üzeneténél), content, visitor_id.
• conversation.ended: conversation_id. A message_count és a duration_seconds mező is szerepel, de ezek értéke jelenleg mindig 0.
• lead.captured: conversation_id, email, name, phone. Ha a látogató csak telefonszámot adott meg, az email üres.
• appointment.created és appointment.cancelled: a foglalás adatai, lásd az Időpontfoglalás oldalt.
• test (a Teszt küldése gombtól): test: true és egy rövid szöveges üzenet.

Aláírás ellenőrzése

Ha a webhooknak van titkos kulcsa, minden kérés X-Webhook-Signature fejlécében ott a nyers kéréstörzs HMAC-SHA256 aláírása, hexadecimális formában, előtag nélkül:

X-Webhook-Signature: 5d41402abc4b2a76b9719d911017c592…

Az aláírást a nyers törzsből számold, még a JSON feldolgozása előtt: egy újra összeállított JSON már más bájtokból állhat. Node.js példa:

import crypto from "node:crypto";

function verifyLexoSignature(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signatureHeader || "", "hex");
  // Állandó idejű összehasonlítás: nem árulja el, hány karakter egyezett.
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// A fogadó végponton:
if (!verifyLexoSignature(rawBody, req.headers["x-webhook-signature"], process.env.LEXO_WEBHOOK_SECRET)) {
  return res.status(401).send("Érvénytelen aláírás");
}

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

• Sikeresnek a 2xx válasz számít. Minden más állapotkód, hálózati hiba vagy időtúllépés hibának.
• A végpontodnak 10 másodpercen belül válaszolnia kell, különben a kérés megszakad.
• Hiba esetén, ha az újrapróbálkozás be van kapcsolva, a rendszer egyre hosszabb várakozással (2, 4, 8… másodperc) újra küldi ugyanazt a payloadot, legfeljebb a beállított számú alkalommal.
• Egy esemény így többször is megérkezhet. Mivel az X-Webhook-Delivery kísérletenként új, az ismétlődést a payload tartalma alapján szűrd ki (pl. event + timestamp + conversation_id).
• Válaszolj gyorsan, és a lassú feldolgozást végezd a válasz után, hogy ne fuss bele az időkorlátba.