Przejdź do głównej treści
Webhook to adres w Twoim systemie (backend, CRM, n8n, Make, Zapier), na który Brosbots wysyła POST z JSON-em, gdy coś się wydarzy: skończy się rozmowa, przyjdzie SMS, kampania obdzwoni listę. Każda wiadomość jest podpisana Twoim kluczem, więc możesz sprawdzić, że przyszła od nas.

Zakładanie webhooka

Integracje → zakładka Własne → kafelek Powiadomienie po zdarzeniu. Kreator ma cztery kroki:
  1. Adres - nazwa, URL i klucz do podpisu. Klucz generuje się sam (whsec_…). Skopiuj go od razu: po zapisaniu pokazujemy go już tylko zamaskowany. Nowy klucz generuje inny; wtedy podmień go też u siebie.
  2. Zdarzenia - które zdarzenia mają przychodzić. call.completed jest zawsze włączone.
  3. Agenci - wszyscy albo tylko wybrani. Zdarzenia przypisane do agenta (rozmowy, SMS-y, kampanie) innych agentów nie trafią na ten adres. balance.low przychodzi zawsze.
  4. Test - wysyła przykładowe zdarzenie, podpisane tak jak prawdziwe. Widzisz kod odpowiedzi Twojego serwera, wysłaną treść i nagłówek podpisu.
Webhook możesz potem edytować w tym samym kreatorze (lista Twoje integracje → Powiadomienia). Ten sam webhook jest też widoczny w katalogu jako Webhook po rozmowie.
Webhooki są dostępne od planu Start.

Format wiadomości

Każde zdarzenie ma tę samą kopertę:
Nagłówki: Przykład z kreatora ma w data pole "test": true, więc łatwo go odfiltrować.

Zdarzenia

Pełne przykłady i opis pól: Payload webhooka po rozmowie.

Sprawdzanie podpisu

Policz HMAC-SHA256 z surowej treści żądania (bajty tak, jak przyszły, przed parsowaniem JSON-a) i porównaj z nagłówkiem w czasie stałym. Ponowne zserializowanie JSON-a może zmienić kolejność kluczy albo spacje, a wtedy podpis się nie zgodzi.
W Make, Zapierze i n8n podpisu zwykle się nie sprawdza: adres webhooka jest tam tajny sam w sobie. Klucz i tak się przydaje, jeśli adres kiedyś wycieknie.

Dostarczanie i ponowienia

  • Odpowiedz kodem 2xx w ciągu 15 sekund. Treść odpowiedzi nie ma znaczenia.
  • Przy błędzie połączenia, przekroczeniu czasu albo kodach 408, 425, 429, 5xx ponawiamy jeszcze dwa razy (po 1 i po 5 sekundach). Inne kody 4xx uznajemy za odrzucenie i nie ponawiamy.
  • Każda próba trafia do Ostatnich wysyłek pod katalogiem integracji, z kodem odpowiedzi i błędem.
  • To samo zdarzenie może w rzadkich przypadkach przyjść dwa razy. Do rozpoznania powtórki użyj event i data.workflow_run_id (albo data.sms_id, data.campaign_id).

Bezpieczeństwo

  • Adres musi być publiczny: adresy w sieci prywatnej i localhost są blokowane.
  • Klucz do podpisu jest przechowywany zaszyfrowany i nie wraca z API w całości.
  • Linki do nagrań i transkrypcji w call.completed działają bez logowania. Traktuj je jak dane osobowe.