Dokumentacja

Webhooki

Wysyłaj podpisane zdarzenia w czasie rzeczywistym do usług zewnętrznych.

Webhooki wysyłają podpisane powiadomienia, gdy zmieniają się leady, formularze, konwersacje lub eskalacje. Wymagają planu Hobby lub wyższego z aktywnymi rozliczeniami.

Konfigurowanie punktu końcowego

Otwórz Ustawienia → Webhooki agenta, wybierz jedno lub więcej zdarzeń, podaj publiczny punkt końcowy HTTPS i utwórz subskrypcje. Agentkit przechowuje jeden sekret podpisywania dla wszystkich wierszy zdarzeń pod tym samym punktem końcowym. Właściciele konta mogą go ujawnić lub obrócić z poziomu karty punktu końcowego.

Obsługiwane nazwy zdarzeń to:

  • lead_created
  • form_submission (starszy alias leada)
  • custom_form_submitted
  • conversation_started
  • conversation_ended
  • escalation_created

conversation_ended jest emitowane po 30 minutach bez żadnej wiadomości. Jego transkrypcja to niezmienny zrzut co najwyżej 200 wiadomości, przy czym każda wiadomość jest ograniczona do 2000 znaków. Konwersacje wyłącznie z Playground oraz te bez żadnej wiadomości użytkownika nie są wysyłane. Analiza transkrypcji ma obecnie wartość null.

Struktura komunikatu (envelope)

Każde zdarzenie ma taką samą, stabilną strukturę:

{
  "event": "conversation_started",
  "eventId": "evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a",
  "timestamp": "2026-07-14T13:05:02.000Z",
  "data": {
    "conversationId": "0b8e43d2-6cdf-42a8-8df1-a17f082df99f",
    "conversationReferenceId": "a1b2c3d4e5f6a7b8",
    "chatbotId": "d21c2aca-52d7-4056-a7d6-805713d3d39c",
    "source": "widget",
    "startedAt": "2026-07-14T13:05:02.000Z"
  }
}

Użyj eventId jako klucza idempotencji. Dostarczenie odbywa się co najmniej raz, a kolejność nie jest gwarantowana. Ten sam identyfikator zdarzenia, znacznik czasu wystąpienia i bajty JSON są używane ponownie przy każdej ponowionej próbie.

Weryfikacja podpisów

Dostarczane żądania zawierają:

X-Agentkit-Event: conversation_started
X-Agentkit-Event-Id: evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a
X-Agentkit-Signature: t=1784043902,v1=<hex-hmac-sha256>

Odczytaj treść żądania jako surowy tekst UTF-8. Sparsuj t i v1, oblicz HMAC-SHA256 z sekretem punktu końcowego na dokładnych bajtach t + "." + rawBody i porównaj skróty za pomocą funkcji działającej w stałym czasie. Nie parsuj i nie serializuj ponownie JSON-a przed weryfikacją. Odrzucaj nieaktualne znaczniki czasu zgodnie ze swoją polityką ochrony przed powtórzeniami.

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

const expected = createHmac('sha256', process.env.AGENTKIT_WEBHOOK_SECRET!)
  .update(`${timestamp}.${rawBody}`, 'utf8')
  .digest('hex');

const valid = timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(v1, 'hex'));

Niezawodność i wyniki

Zwróć status 2xx w ciągu 10 sekund. Odpowiedź inna niż 2xx, przekroczenie limitu czasu lub błąd sieci skutkuje pięcioma ponownymi próbami po żądaniu początkowym (zwykle sześć prób łącznie), z rosnącym opóźnieniem między próbami (QStash backoff). Strona ustawień pokazuje 20 ostatnich wyników końcowych.

Jedno wyczerpane zdarzenie zwiększa licznik kolejnych niepowodzeń tylko raz, niezależnie od liczby prób czy zduplikowanych wywołań zwrotnych. Subskrypcja zostaje automatycznie wyłączona dopiero po co najmniej 10 kolejnych wyczerpanych zdarzeniach rozłożonych na co najmniej siedem dni. Właściciele otrzymują jedno powiadomienie z możliwością ponowienia i mogą ponownie włączyć subskrypcję po naprawieniu problemu. Udane zdarzenie zeruje licznik.

Adresy URL punktów końcowych muszą używać protokołu HTTP lub HTTPS, muszą być publiczne i nie mogą wskazywać na localhost, prywatne/łącza lokalne zakresy adresów IP ani punkty końcowe metadanych chmury. Środowisko produkcyjne wymaga HTTPS. W momencie dostarczenia Agentkit rozwiązuje nazwę hosta jednokrotnie, wymaga, aby każdy rozwiązany adres był publiczny, i przypina połączenie do tych adresów, dzięki czemu DNS rebinding nie może przekierować dostarczenia na adres wewnętrzny.

Aktywacja harmonogramu

Kod odpowiedzialny za przegląd nieaktywnych konwersacji jest domyślnie wyłączony. Operator może go przejrzeć i po wdrożeniu uruchomić polecenie pnpm --filter chatbots setup:idle-conversation-webhooks. Polecenie tworzy 15-minutowy harmonogram QStash; samo scalenie kodu go nie tworzy ani nie włącza.

Kolejne kroki