Webhooki #

Webhooki pozwalają Your AI Connector automatycznie powiadamiać inne narzędzia biznesowe, gdy wydarzy się coś ważnego — utworzenie nowego kontaktu, umówienie spotkania czy otrzymanie wiadomości. Zamiast ręcznie sprawdzać aktualizacje, połączone systemy otrzymują natychmiastowe powiadomienie w momencie, gdy coś się wydarzy.

Czym są webhooki? #

Pomyśl o webhooku jak o automatycznej wiadomości tekstowej między dwiema aplikacjami. Gdy coś wydarzy się w Your AI Connector (np. zarejestruje się nowy kontakt), platforma natychmiast wysyła powiadomienie do wybranego przez Ciebie systemu. Podajesz adres internetowy (zwany „adresem URL webhooka”), na który mają być wysyłane te powiadomienia — zazwyczaj jest on dostarczany przez Twój system CRM, platformę do automatyzacji lub programistę.

Strona Webhooki wysyła dane WYŁĄCZNIE z Your AI Connector. Skonfigurowane tutaj webhooki działają jednokierunkowo, z Your AI Connector do Twoich innych narzędzi. Aby zaimportować nowy lead lub inne dane (z formularza na stronie, systemu CRM lub GoHighLevel), masz dwie opcje. Automatyzacja z wyzwalaczem Webhook udostępnia adres internetowy, pod który Twój formularz lub narzędzie może wysyłać dane, a jej kroki mogą następnie utworzyć kontakt, wysłać wiadomość i nie tylko. Alternatywnie Twój system może wykonać wywołanie API, na przykład operację Utwórz kontakt, używając Twojego klucza API; zobacz Dostęp do API oraz Lejki.

Webhooki są dostępne tylko w niektórych planach. Jeśli Twój plan nie obejmuje webhooków, strona Webhooki nie będzie dostępna i żadne zdarzenia nie będą wysyłane. Wszystko, co zapisałeś wcześniej, pozostaje na Twoim koncie i zacznie być ponownie wysyłane, gdy tylko przejdziesz na plan obejmujący webhooki. Funkcje Twojego planu są wymienione na stronie rozliczeniowej, a Twój dostawca może poinformować Cię, na który plan warto przejść.

Typowe zastosowania obejmują:

• Synchronizację nowych kontaktów z Twoim systemem CRM.
• Uruchamianie przepływu pracy w Zapier, Make lub Pabbly po przypisaniu tagu.
• Powiadamianie zespołu na Slacku, gdy użytkownik zostanie zaalarmowany.
• Aktualizację systemu kalendarza po umówieniu spotkania.
• Zapisywanie podsumowań rozmów w Twojej bazie danych.

Konfigurowanie webhooków #

1. Na lewym pasku bocznym kliknij Ustawienia (ikona koła zębatego).
2. Na pasku bocznym Ustawień, w grupie Integracje, kliknij Webhooki.

Na koncie, na którym nie skonfigurowano jeszcze żadnych webhooków, strona wygląda następująco:

3. Kliknij Nowy webhook w prawym górnym rogu. Na stronie otworzy się formularz:

4. Wypełnij:
   • Adres URL punktu końcowego (Endpoint URL) — adres internetowy, na który Your AI Connector będzie wysyłać powiadomienia o zdarzeniach. Otrzymasz go od swojego systemu zewnętrznego (CRM, platformy do automatyzacji lub własnego serwera).
   • Nazwa — etykieta, którą rozpoznasz później (np. „Powiadomienia Slack” lub „Synchronizacja CRM”). Tylko do Twojego wglądu.

Twój adres URL webhooka musi być publicznie dostępnym adresem https://. Zwykłe adresy http://, adresy localhost lub adresy sieci prywatnych oraz adresy wewnętrzne platformy są odrzucane podczas zapisu. Aby przetestować webhooka z własnego komputera, użyj publicznego tunelu (webhook.site lub ngrok) zamiast localhost.

5. W sekcji Zdarzenia (Events) kliknij zdarzenia, które ma otrzymywać ten webhook — wszystkie 24 są wymienione w The 24 Webhook Events.
6. (Opcjonalnie) Włącz Ponów nieudane dostarczenia (Retry failed deliveries), jeśli chcesz, aby Your AI Connector ponawiał próby w przypadku tymczasowej awarii — zobacz Retrying Failed Deliveries.
7. Kliknij Utwórz webhook (Create webhook). Pojawi się on na liście pod formularzem i w każdej chwili możesz kliknąć Test w jego wierszu, aby wysłać przykładowy ładunek (payload) do swojego punktu końcowego.

Wymagane uprawnienia. Dodawanie, edytowanie lub testowanie webhooków wymaga uprawnienia „edit” dla integracji (członkowie zespołu z uprawnieniami tylko do odczytu zobaczą powiadomienie o braku dostępu zamiast formularza).

Podpisywanie webhooka wymaga jego wcześniejszego zapisania — otwórz wiersz istniejącego webhooka, aby go edytować, a panel Signing secret pojawi się na dole formularza edycji. Nowy, niezapisany szkic nie ma jeszcze opcji podpisywania — zobacz Podpisane ładunki poniżej.

Jeden webhook dla wszystkich kont Twoich klientów (agencje) #

Jeśli prowadzisz agencję, nie musisz tworzyć tego samego webhooka na każdym koncie klienta z osobna. Na koncie agencji formularz webhooka posiada dodatkowy przełącznik: Wywołuj również dla wszystkich kont klientów. Włącz go, a ten webhook będzie otrzymywał również zdarzenia, które mają miejsce na każdym koncie klienta w ramach Twojej agencji — jeden punkt końcowy dla całej agencji.

Jak to działa:

• Blok user informuje, do którego klienta należy zdarzenie. Każde powiadomienie zawiera już blok user identyfikujący konto, na którym wystąpiło zdarzenie, dzięki czemu Twoja automatyzacja może kierować ruch dla każdego klienta z osobna.
• Ustawienia Twojego webhooka mają zastosowanie wszędzie. Wybrane zdarzenia, klucz podpisywania oraz ustawienie ponawiania są używane również w przypadku dostaw na konta klientów.
• Brak podwójnych dostaw. Jeśli konto klienta posiada własny webhook wskazujący na ten sam adres URL, to on zostanie użyty do obsługi zdarzeń tego konta — to samo zdarzenie nigdy nie trafi dwukrotnie do jednego punktu końcowego.
• Klienci go nie widzą. Webhook nie pojawia się na stronie Webhooków konta klienta, a klienci nie mogą go wyłączyć — zarządzanie nim należy wyłącznie do Ciebie.
• Niezawodność jest śledzona dla każdego konta klienta z osobna. Jeśli Twój punkt końcowy stale zawodzi, zostanie automatycznie wyłączony dla konta, którego dostawy nie powiodły się (zobacz Niezawodność webhooków), a nie dla całej agencji jednocześnie.

Przełącznik pojawia się tylko na kontach agencji. Obsługiwane jest również ustawianie go przez API — zobacz pole apply_to_sub_accounts w API Webhooków.

Dostępne zdarzenia wyzwalające #

Możesz niezależnie włączać lub wyłączać każde z 24 zdarzeń webhooka. Gdy zdarzenie zostanie wywołane, Your AI Connector wysyła powiadomienie na Twój adres URL webhooka z odpowiednimi danymi. Każde zdarzenie, jego znaczenie oraz kod event, który umieszcza w ładunku, są wymienione razem w The 24 Webhook Events w dalszej części tej strony.

Warto wiedzieć: Zadanie utworzone (Task Created), Zadanie zaktualizowane (Task Updated) oraz Zadanie ukończone (Task Completed) są w pełni wybieralne i zapisują się poprawnie. Utworzono podsumowanie dzienne (Daily Summary Created) to również niedawny dodatek. Zobacz Webhook ukończenia zadania poniżej, aby sprawdzić strukturę tego ładunku.

Wyzwalacze webhooków oparte na tagach #

subscribed_to_tags nie ogranicza zdarzeń webhooka do konkretnego tagu. Ogranicza jedynie to, które tagi generują powiadomienie o podsumowaniu rozmowy. Aby otrzymać żądanie po przypisaniu określonego tagu, ustaw adres URL webhooka dla tego tagu w zakładce Tagi w edytorze agenta.

Sam formularz webhooka nie posiada selektora tagów, ani podczas tworzenia nowego webhooka, ani podczas edycji istniejącego, więc subscribed_to_tags można odczytać lub zmienić tylko za pośrednictwem API Webhooków lub kontaktując się z pomocą techniczną.

Warto wiedzieć: edycja istniejącego webhooka, który posiada listę subscribed_to_tags (zmiana nazwy, zmiana zdarzeń, przełączanie ponownych prób), nie czyści już tej listy — ponieważ formularz nie posiada selektora tagów do odesłania, zapisanie zmian z tej strony pozostawia istniejącą listę nienaruszoną. (Był to rzeczywisty błąd przed 21 lipca 2026 r.: zapisywanie z poziomu formularza webhooka usuwało listę, ponieważ zawsze wysyłało pustą listę tagów. Jeśli webhook utracił swoją listę subscribed_to_tags przed tą datą, będzie wymagał ponownej konfiguracji przez API.)

Generowanie podsumowania dla otagowanych kontaktów #

Jeśli webhook posiada listę subscribed_to_tags, możesz włączyć Generuj podsumowanie (Generate Summary). Po włączeniu Your AI Connector automatycznie generuje podsumowanie konwersacji dla kontaktu, gdy jeden z tych tagów zostanie zastosowany, i dołącza je do danych webhooka — pełny kontekst bez konieczności wysyłania osobnego żądania.

Testowanie webhooka #

1. Otwórz Ustawienia → Integracje → Webhooki.
2. W wierszu swojego webhooka kliknij Testuj.
3. Sprawdź swój system zewnętrzny, aby potwierdzić, że otrzymał dane testowe.
4. Przejrzyj format danych, aby upewnić się, że Twój system może je poprawnie przetworzyć.

Aby przeprowadzić pełny test typu end-to-end, wyślij wiadomość, która wywołałaby jedno z Twoich skonfigurowanych zdarzeń (transmisję lub wiadomość przychodzącą na połączony kanał) i zweryfikuj, czy webhook uruchamia się z rzeczywistymi danymi.

Co uznaje się za udane dostarczenie #

Niezależnie od tego, czy klikniesz Testuj, czy zdarzenie wystąpi naprawdę, wysyłamy to samo:

• Żądanie POST (nigdy GET), z treścią (body) w formacie JSON i Content-Type: application/json.
• Nagłówki wymienione w sekcji Podpisane ładunki. Nagłówki podpisu są dołączane tylko wtedy, gdy ustawisz klucz podpisywania (signing secret).

Dostarczenie uznajemy za udane, gdy:

• Twój punkt końcowy odpowiada dowolnym statusem 2xx (200, 201, 204 — wszystkie są poprawne).
• Odpowiada w ciągu 30 sekund.

Kilka rzeczy, które zaskakują użytkowników:

• Treść odpowiedzi jest ignorowana. Nie musisz zwracać żadnego konkretnego pliku JSON. Wystarczy pusta odpowiedź 200.
• Przekierowania są traktowane jako błąd. Nie podążamy za nimi, więc kod 301 lub 302 (w tym przekierowanie z ukośnikiem na końcu lub z http na https) jest rejestrowany jako nieudane dostarczenie. Zapisz ostateczny adres URL, a nie ten, który przekierowuje.
• Ciągi zapytań (query strings) są w pełni obsługiwane. https://your-app.com/hook?token=abc123 jest wysyłany dokładnie tak, jak go zapisałeś, więc umieszczenie tokena w ciągu zapytania działa tak samo dobrze, jak umieszczenie go w ścieżce.
• Twój adres URL musi być https:// i publicznie dostępny. Adresy należące do własnej infrastruktury Your AI Connector są odrzucane, ale Twoje własne punkty końcowe w Google Cloud Functions, Cloud Run, App Engine, Firebase Hosting lub gdziekolwiek indziej są w porządku.
• Zapora sieciowa lub warstwa ochrony przed botami przed Twoim punktem końcowym może nas blokować. Najczęstszym przypadkiem jest Cloudflare: jeśli Twoja strefa ma włączony tryb Bot Fight Mode lub zarządzane wyzwanie, nasze żądanie otrzymuje stronę z wyzwaniem „Just a moment…” z kodem 403 zamiast dotrzeć do Twojego serwera — a żądanie serwer-serwer nigdy nie przejdzie wyzwania przeglądarkowego, więc zarówno przycisk Test, jak i rzeczywiste zdarzenia kończą się niepowodzeniem w ten sam sposób. Przycisk Test poinformuje Cię, kiedy tak się dzieje („Cloudflare wyświetla wyzwanie bota dla naszego żądania”). Napraw to w Cloudflare za pomocą reguły Security / WAF, która pomija wyzwania dla Twojej ścieżki webhooka (lub dla agenta użytkownika Webhook-Delivery/1.0), a następnie kliknij ponownie Test.
• Jeśli Twoja zapora sieciowa wymaga listy dozwolonych adresów IP (na przykład w darmowym planie Cloudflare, gdzie zwykłego trybu Bot Fight Mode nie można pominąć regułą WAF, ale reguła dostępu IP ustawiona na Zezwalaj działa przed nim), możemy pomóc: każde dostarczenie, czy to z przycisku Test, czy z wydarzenia na żywo, jest wysyłane z jednego stałego adresu IPv4 (bez zakresów, bez IPv6, bez rotacji). Skontaktuj się z pomocą techniczną, a podamy Ci adres do umieszczenia na liście dozwolonych. Zachowaj weryfikację podpisu jako właściwą kontrolę zaufania, ponieważ sprawdza ona każdy ładunek niezależnie od tego, skąd pochodzi.
• Wynik testu dokładnie pokazuje, co odpowiedział Twój punkt końcowy. Nieudany test pokazuje teraz rzeczywisty powód (kod stanu HTTP zwrócony przez Twój punkt końcowy, przekroczenie limitu czasu lub brak możliwości dotarcia do adresu) zamiast ogólnego błędu, a test zapisanego webhooka jest wysyłany z podpisem, gdy podpisywanie jest włączone, dokładnie tak jak w przypadku zdarzenia na żywo.

Korzystanie z n8n, Make lub Zapier („Testowy URL” vs „Produkcyjny URL”) #

Platformy automatyzacji zazwyczaj udostępniają dwa różne adresy webhooków, co często wprowadza użytkowników w błąd:

• Testowy URL (w n8n zawiera /webhook-test/). Otrzymuje dane tylko wtedy, gdy aktywnie obserwujesz obszar roboczy i właśnie kliknąłeś Listen for test event (lub Test workflow). Przechwytuje jedno zdarzenie, a następnie przestaje nasłuchiwać — więc wielokrotne klikanie Testuj w Your AI Connector z rzędu przechwyci tylko pierwsze z nich, i to tylko wtedy, gdy okno nasłuchiwania jest w tym momencie aktywne. Aby przetestować: najpierw kliknij Listen for test event w n8n, a następnie wróć do Your AI Connector i kliknij Testuj raz.
• Produkcyjny URL (w n8n zawiera /webhook/, bez -test). To ten adres należy wkleić do Your AI Connector dla zdarzeń na żywo. Działa tylko wtedy, gdy Twój przepływ pracy (workflow) jest ustawiony jako Active. Jeśli przepływ pracy nie jest aktywny, n8n odrzuci żądanie błędem „404 / webhook not registered”, mimo że Your AI Connector wysłał dane poprawnie.

Krótko mówiąc: testuj za pomocą Testowego URL-a podczas nasłuchiwania, ale aby webhook działał dla rzeczywistych kontaktów, zapisz Produkcyjny URL w Your AI Connector i upewnij się, że przepływ pracy jest Active.

Format danych webhooka #

Gdy webhook zostaje wywołany, Your AI Connector wysyła ustrukturyzowane dane (JSON) na Twój adres URL webhooka. Jeśli korzystasz z platformy do automatyzacji, takiej jak Zapier lub Make, dane te są parsowane automatycznie. Jeśli tworzysz własną integrację:

{
  "event": "contactCreated",
  "contact": { "id": "<contact-id>", "first_name": "Jane", "...": "..." },
  "campaign": { "id": "<campaign-id>", "name": "AI Receptionist", "status": "Live" },
  "agent": { "id": "<agent-id>", "name": "Front Desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" }
}

Czytaj agent, a nie campaign. Kampanie zostały przeniesione do Agentów AI i Transmisji (zobacz Kampanie zostały przeniesione), więc Twoje kontakty są przypisane do agenta, a agent informuje Cię, który z nich obsługiwał rozmowę. Pole campaign jest nadal wysyłane, aby starsze odbiorniki działały poprawnie, ale zazwyczaj jest to null; jest wypełniane tylko dla kontaktu, który nadal posiada powiązanie z klasyczną kampanią. Nie zakładaj, że campaign zawsze tam jest.

Blok agent pojawił się 15 sierpnia 2026 r. Znajduje się on obok campaign w zdarzeniach powiązanych z konwersacją — zakończonym czatem, trybem nie przeszkadzać, wznowieniem, przywróceniem z archiwum, wstrzymaniem AI, nową wiadomością, podsumowaniem konwersacji oraz webhookiem, który można ustawić dla tagu — i zawiera id oraz name agenta obsługującego, lub null, gdy żaden agent nie jest zaangażowany. Jest to zmiana czysto addytywna: każde pole, które już otrzymujesz, pozostaje bez zmian, więc odbiornik zbudowany przed tą datą będzie nadal działał bez konieczności wprowadzania aktualizacji.

Niektóre zdarzenia dodają własny, dodatkowy blok najwyższego poziomu. Na przykład Appointment Booked (Spotkanie zarezerwowane), Appointment Cancelled (Spotkanie anulowane) i Appointment Rescheduled (Spotkanie przełożone) dodają blok appointment (zobacz Appointment Booked Webhook), New Message (Nowa wiadomość) dodaje pełny blok message z tekstem (zobacz New Message Webhook), a Deliveries (Dostarczenia) i Reads (Odczytania) dodają krótki blok message tylko z identyfikatorem i statusem wiadomości (zobacz Deliveries and Reads Webhook).

Deliveries i Reads informują, której wiadomości dotyczą, ale nie podają jej treści. Zawierają blok message z id i status wiadomości — a ten id jest tym samym messageId, który zwraca punkt końcowy wysyłania wiadomości, dzięki czemu możesz dopasować potwierdzenie dostarczenia lub odczytania do konkretnej wysłanej wiadomości — ale bez treści samej wiadomości. Replies nie zawiera żadnego bloku message. Jeśli potrzebujesz treści wysłanych lub odebranych wiadomości, zasubskrybuj również New Message.

Dwie rzeczy, które warto wiedzieć przed napisaniem odbiornika. Nie ma pola timestamp ani otoki data. Każdy blok znajduje się na najwyższym poziomie obiektu JSON, jak pokazano powyżej.

The 24 Webhook Events #

24 zdarzenia webhooka wraz z etykietą wyświetlaną, którą zaznaczasz w aplikacji, oraz kodem event wysyłanym w ładunku. Kod event to krótki ciąg znaków, który nie pasuje do etykiety wyświetlanej, więc dopasowuj odbiorcę na podstawie kodu, a nie etykiety:

Dwa kolejne kody nigdy nie pojawiają się na tej liście, ponieważ nie subskrybujesz ich: contact_tags_updated, wysyłany przez adres URL webhooka ustawiony na indywidualnym tagu, oraz summary_generated, wysyłany, gdy podsumowanie czatu jest zapisywane dla tagu na liście subscribed_to_tags webhooka.

Zdarzenie Kanał połączony nie jest jeszcze wysyłane. Pojawia się na liście zdarzeń, ale obecnie nic go nie wywołuje. Nie opieraj na nim żadnych funkcji.

Powiadomienia oparte na tagach i zadaniach używają własnych, oddzielnych struktur. Zobacz Contact Tags Updated oraz Task Completed.

Webhook Contact Created #

Wysyłany, gdy wyzwalane jest zdarzenie Contact Created (nowy kontakt dodany ręcznie, poprzez import lub przez API).

Nazwa zdarzenia #

contactCreated

Format ładunku (payload) #

{
  "event": "contactCreated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null,
    "ad_attribution": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

Próbka „Test” i rzeczywiste zdarzenie wyglądają nieco inaczej. Przycisk testowy wysyła przykładowe dane (Jan Kowalski, przykładowy blok kampanii). Rzeczywiste zdarzenie utworzenia kontaktu zawiera szczegółowe dane konkretnego kontaktu, a niektóre pola mogą być puste w zależności od kanału.

Webhook nowej wiadomości #

Ten webhook uruchamia się za każdym razem, gdy wiadomość jest dodawana do rozmowy, w dowolnym kanale. Obejmuje oba kierunki: wiadomości wysyłane przez kontakt do Ciebie oraz wiadomości wysyłane do niego przez Twojego agenta AI, Twój zespół lub transmisję. Jest to jedyny webhook, który zawiera treść wiadomości, więc należy go użyć, jeśli chcesz odzwierciedlać rozmowy w zewnętrznym systemie.

Nazwa zdarzenia #

new_message

Format ładunku (payload) #

{
  "event": "new_message",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null,
    "ad_attribution": null
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "body": "Hi, are you open on Saturday?",
    "direction": "inbound",
    "status": "received",
    "created_at": "2026-07-30T17:27:06.000Z",
    "channel": "whatsapp_web",
    "media_url": null,
    "media_content_type": null
  }
}

W tym ładunku nadal nie ma bloku campaign. Nowa wiadomość wysyła contact, agent, user i message. Blok agent został dodany 15 sierpnia 2026 r. i informuje, który agent obsługuje rozmowę; jeśli potrzebujesz więcej kontekstu na temat kontaktu, wyszukaj go przez API, używając contact.id.

Zapisuj załączniki krótko po ich otrzymaniu. Link media_url przestaje działać 7 dni po otrzymaniu wiadomości, na każdym kanale (WhatsApp Business API, WhatsApp Web, Instagram, Messenger, Telegram, widżet czatu i inne); sam plik pozostaje. Aby uzyskać nowy link później, wywołaj Pobierz załącznik wiadomości za pomocą contacts/{contact.id}/messages/{message.id}. Pola zostały dodane 13 września 2026 r.

Gdy media_url to null, ale treść wskazuje, że dotarł plik. Niektóre załączniki są przechowywane w sposób, który nie ma bezpośredniego linku, a udostępniony post, relacja lub wzmianka na Instagramie to link do Instagrama, a nie plik, więc one również docierają jako null (treść wskazuje, co zostało udostępnione). W przypadku pliku wywołaj Download a message’s attachment z identyfikatorem wiadomości, aby uzyskać link.

Zaimportowana historia nie wyzwala tego webhooka. Gdy numer WhatsApp Web importuje swoje poprzednie konwersacje, te starsze wiadomości są zapisywane bez powiadomienia o każdej nowej wiadomości.

Wewnętrzne rekordy AI nie uruchamiają tego webhooka. Oprócz rzeczywistych wiadomości platforma przechowuje własne wiersze księgowe w konwersacji (wywołania narzędzi AI i wewnętrzne rekordy tur). Nigdy nie są one wysyłane — otrzymujesz tylko wiadomości, które zostały faktycznie wysłane lub odebrane.

Webhook Deliveries and Reads #

Te dwa zdarzenia raportują, co stało się z wiadomością po tym, jak opuściła Your AI Connector: Deliveries wyzwala się, gdy wiadomość dotrze do kontaktu (lub nie uda się jej dostarczyć), a Reads wyzwala się, gdy kontakt ją otworzy, na kanałach obsługujących potwierdzenia odczytu.

Oba zawierają blok message z identyfikatorem wiadomości, której dotyczy zdarzenie, dzięki czemu możesz dopasować aktualizację do konkretnej wysłanej wiadomości.

Nazwy zdarzeń #

delivered i undelivered dla Deliveries, read dla Reads.

Format ładunku (payload) #

{
  "event": "delivered",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "ad_referral": null,
    "ad_attribution": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "status": "delivered"
  }
}

Jak dopasować aktualizację do wysłanej wiadomości. Przechowuj messageId, który otrzymujesz po wysłaniu wiadomości przez API. Gdy nadejdzie powiadomienie Deliveries lub Reads, wyszukaj ten zapisany identyfikator w polu message.id w ładunku — to jest Twoje potwierdzenie dostarczenia lub odczytania dla tej konkretnej wiadomości.

Tutaj nie ma tekstu wiadomości. Blok message zawiera tylko identyfikator i status. Zasubskrybuj New Message, jeśli potrzebujesz również treści wiadomości.

Blok message jest obecny tylko wtedy, gdy wiemy, o jaką wiadomość chodzi. W rzadkich przypadkach aktualizacji, których nie możemy powiązać z zapisaną wiadomością, blok jest całkowicie pomijany, zamiast być wysyłanym jako pusty — dlatego sprawdź, czy message istnieje, zanim odczytasz message.id.

Jedno powiadomienie na zmianę statusu. Pojedyncza wiadomość wychodząca zazwyczaj generuje powiadomienie delivered, a następnie, na kanałach z potwierdzeniami odczytu, powiadomienie read. Nieudana wysyłka generuje zamiast tego undelivered.

Webhook rezerwacji spotkania #

Uruchamia się, gdy kontakt zarezerwuje spotkanie. Uruchamia się w ten sam sposób, niezależnie od tego, czy sztuczna inteligencja zarezerwowała je podczas konwersacji, czy Ty zarezerwowałeś je ręcznie, czy też wpłynęło ono przez API.

Nazwa zdarzenia #

booked

Format ładunku (payload) #

{
  "event": "booked",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com"
  },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z",
    "status": "Confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": null,
    "external_reference": "crm-booking-1042",
    "event": {
      "id": "<service-id>",
      "event_name": "Intro Call",
      "slot_duration": 30,
      "location": "Zoom",
      "meeting_link": "https://...",
      "event_type": "online"
    }
  }
}

google_calendar_event_id jest często null w tym webhooku i jest to normalne. Wydarzenie w Kalendarzu Google jest tworzone w tym samym momencie, w którym wysyłane jest powiadomienie, więc identyfikator zazwyczaj nie jest jeszcze gotowy. Jeśli go potrzebujesz, pobierz ponownie spotkanie za pomocą jego appointment_id chwilę później. Pozostaje ono null na stałe, jeśli konto nie ma połączonego Kalendarza Google, więc nie czekaj na nie w nieskończoność.

Przycisk “Test” wysyła przykładowy blok appointment ze zmyślonymi wartościami, dzięki czemu możesz budować w oparciu o strukturę, zanim nadejdzie prawdziwa rezerwacja.

Dwa przypadki, w których ten webhook nie jest wyzwalany: spotkania zaimportowane z zewnętrznego kalendarza oraz rezerwacje pochodzące z integracji Formitable.

Appointment Cancelled and Rescheduled Webhooks #

Appointment Cancelled wyzwala się, gdy spotkanie zostaje anulowane, a Appointment Rescheduled wyzwala się, gdy zostaje przeniesione na nowy czas rozpoczęcia lub zakończenia. Oba wyzwalają się w ten sam sposób, niezależnie od tego, czy zrobiło to AI podczas konwersacji, czy zmieniłeś to w aplikacji, czy przyszło przez API, czy ktoś zmienił zdarzenie w połączonym Kalendarzu Google.

Nazwy zdarzeń #

appointment_cancelled i appointment_rescheduled

Format ładunku (payload) #

Treść jest taka sama jak w Appointment Booked, ze spotkaniem w stanie po zmianie. Anulowanie dodaje appointment.cancelation_reason; przełożenie dodaje blok najwyższego poziomu previous ze starymi czasami:

{
  "event": "appointment_rescheduled",
  "contact": { "id": "<contact-id>", "email": "jane@example.com", "phone_number": "+15551234567", "first_name": "Jane", "last_name": "Smith" },
  "campaign": null,
  "agent": { "id": "<agent-id>", "name": "Front desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-21T09:00:00.000Z",
    "end_time": "2026-07-21T09:30:00.000Z",
    "status": "Confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": "<calendar-event-id>",
    "external_reference": "crm-booking-1042",
    "cancelation_reason": null,
    "event": { "id": "<service-id>", "event_name": "Intro Call", "slot_duration": 30 }
  },
  "previous": {
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z"
  }
}

Jedna zmiana, jedno zdarzenie. Anulowanie spotkania wysyła tylko Appointment Cancelled, nawet jeśli jego czas zmienił się w tej samej edycji. Edycja tylko tytułu, notatek lub pokoju nie wysyła żadnego z nich. Przeniesienie tego samego spotkania dwukrotnie wysyła dwa zdarzenia Appointment Rescheduled.

Webhook Zakończenia czatu #

Uruchamia się, gdy AI uzna, że rozmowa dobiegła końca (dokonano rezerwacji, zdyskwalifikowano leada itp.).

Nazwa zdarzenia #

chat_concluded

Format ładunku (payload) #

Ładunek zawiera event, pełne contact, agent, który obsługiwał czat, oraz user konta. Zawiera również conversation_cost, czyli koszt tej rozmowy w kredytach, dzięki czemu przepływ w n8n lub Make może go zarejestrować bez drugiego wywołania:

{
  "event": "chat_concluded",
  "contact": { "id": "abc123", "first_name": "Jane", "channel": "whatsapp" },
  "agent": { "id": "agent_1", "name": "Sales Agent" },
  "user": { "id": "user_1" },
  "conversation_cost": {
    "credits": 7.5,
    "session_id": "sess_9f2",
    "started_at": "2026-09-26T09:14:02.000Z",
    "outcome": "contained"
  }
}

• credits: kredyty pobrane w ramach tej rozmowy, po uwzględnieniu zwrotów. Jest to liczone w ten sam sposób, co raport kosztów rozmów w API.
• outcome: contained (AI obsłużyło to samodzielnie), handed_off (ktoś z Twojego zespołu odpowiedział po AI lub AI zaalarmowało człowieka) lub no_ai.
• conversation_cost jest pomijane, gdy wartości nie można w danej chwili obliczyć. Traktuj to jako opcjonalne.

Webhook aktualizacji tagów kontaktu #

Uruchamia się, gdy tag jest przypisywany do kontaktu, a ten tag ma skonfigurowany adres URL webhooka u agenta, do którego przypisany jest kontakt.

Nazwa zdarzenia #

contact_tags_updated

Kiedy jest wyzwalane #

• Do kontaktu, któremu przypisano agenta AI, stosowana jest etykieta.
• Co najmniej jedna z zastosowanych etykiet ma ustawiony adres URL webhooka w karcie Etykiety edytora tego agenta.

Kontakt, który nadal posiada powiązanie z klasyczną kampanią sprzed przejścia na agentów, jest przypadkiem szczególnym: jeśli etykiety tej kampanii zawierają adresy URL webhooków, są one używane; w przeciwnym razie używane są adresy agenta.

Jeśli w tej samej aktualizacji przypisanych zostanie wiele etykiet z różnymi adresami URL webhooków, wysyłane jest jedno żądanie na każdy adres URL, z których każde zawiera tylko etykiety przypisane do tego konkretnego adresu.

Usunięcie etykiety nigdy nie powoduje wysłania żądania. Większość użytkowników kieruje te adresy URL do określonych działań — pobrania zaliczki, zarezerwowania terminu, powiadomienia przedstawiciela — więc ponowne pojawienie się etykiety u kontaktu mogłoby spowodować ponowne uruchomienie tego działania. Teraz nie jest to już możliwe. Usunięcie nadal pojawia się w removed_tags, jeśli wystąpi w tej samej aktualizacji co przypisanie, które kieruje do tego samego adresu URL, dzięki czemu automatyzacja odczytująca obie tablice zachowuje pełny obraz sytuacji; nigdy jednak nie zobaczy żądania wywołanego wyłącznie usunięciem. (Zmieniono 12 sierpnia 2026 r. Przed tą datą usunięcia również wysyłały żądanie.)

Format ładunku (payload) #

{
  "event": "contact_tags_updated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "is_bot_active": true,
    "ad_referral": {
      "ctwa_clid": "ARAbc123...",
      "source_id": "120210000000000",
      "source_type": "ad",
      "source_url": "https://fb.me/xxxx",
      "headline": "Get 20% off today",
      "body": "Message us now to claim your discount",
      "channel": "whatsapp"
    },
    "ad_attribution": null
  },
  "added_tags": ["qualified-lead"],
  "removed_tags": ["new-lead"],
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

Testowanie webhooka tagu #

Obok pola adresu URL webhooka na karcie Tagi znajduje się przycisk Testuj. Wysyła on natychmiast przykładowy ładunek (payload) pod ten adres, dzięki czemu możesz potwierdzić, że Twoja automatyzacja go odbiera, bez konieczności czekania na rzeczywistą konwersację.

Test wysyła ten sam kształt contact_tags_updated, który pokazano powyżej, używając przykładowego kontaktu, z tagiem, który testujesz w added_tags oraz pustym removed_tags. To, co Twoja automatyzacja widzi w teście, jest tym samym, co zobaczy w środowisku produkcyjnym.

Warto wiedzieć o dwóch rzeczach:

• Najpierw zapisz tag. Test wyszukuje tag po jego zapisanej nazwie, więc zupełnie nowy tag lub niezapisana zmiana nazwy nie mogą być jeszcze przetestowane. Przycisk pozostaje wyszarzony, dopóki nazwa na ekranie nie będzie zgodna z zapisaną.
• Nieudany test nie wpływa na Twój webhook. Testy nigdy nie przyczyniają się do automatycznego wyłączenia po wielokrotnych awariach, opisanego w Niezawodność Webhooków.

Jeśli test się nie powiedzie, komunikat poinformuje Cię, co odpowiedział Twój punkt końcowy (na przykład 404 lub 500), co zazwyczaj wystarcza, aby wykryć błędny adres URL lub przepływ pracy, który nie jest włączony.

Webhook ukończenia zadania #

Tylko w celach informacyjnych. Webhooki zadań (jako dane) są udokumentowane tutaj dla programistów; zdarzenia Task Created, Task Updated i Task Completed można wybrać na standardowej liście zdarzeń w formularzu webhooka, tak jak każde inne zdarzenie — zobacz Available Trigger Events oraz The 24 Webhook Events.

Ten ładunek jest wysyłany, gdy zadanie przechodzi do etapu oznaczonego jako etap ukończenia. Zadanie przenoszone między etapami niebędącymi etapami ukończenia wysyła zamiast tego strukturę taskUpdated.

Nazwa zdarzenia #

taskCompleted

Kiedy jest wyzwalane #

• Zadanie zostało zaktualizowane.
• Jego wartość stage zmieniła się w porównaniu z poprzednią wartością.
• Nowy etap jest skonfigurowany jako etap ukończenia w ustawieniach etapów zadań na koncie.

Format ładunku (payload) #

{
  "event": "taskCompleted",
  "contact": {
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<task-id>",
    "title": "Follow up with Jane",
    "description": "Confirm pricing and send proposal",
    "type": "follow_up",
    "priority": "high",
    "stage": "<stage-id>",
    "due_date": "2026-01-20T15:00:00Z",
    "source": "ai",
    "source_detail": "<source-detail>",
    "campaign_id": "<campaign-id>",
    "linked_human_alert": "<human-alert-id>",
    "tags": ["qualified-lead"],
    "notes": "Customer requested a callback"
  }
}

Wyłączanie (lub usuwanie) webhooka #

Każdy webhook posiada przełącznik włączania/wyłączania, znajdujący się bezpośrednio w jego wierszu. Wyłączenie go powoduje wstrzymanie otrzymywania zdarzeń, ale zachowuje wszystko, co skonfigurowałeś — adres URL, zdarzenia, wszelkie klucze podpisywania. Po ponownym włączeniu webhook zacznie działać od miejsca, w którym przerwał; żadne zdarzenia, które wystąpiły w czasie, gdy był wyłączony, nie zostaną dostarczone później.

Użyj tej opcji, gdy chcesz na pewien czas wstrzymać dostarczanie: Twój punkt końcowy jest przebudowywany, debugujesz uciążliwą integrację lub wstrzymujesz automatyzację.

Usuwanie webhooka (ikona kosza w jego wierszu) usuwa go na stałe, włącznie z jego kluczem podpisywania. Jeśli chcesz tylko wstrzymać dostarczanie, zamiast tego wyłącz go — usuwanie służy do sytuacji, w których całkowicie rezygnujesz z danego punktu końcowego.

To nie to samo, co automatyczne wyłączenie webhooka. Jeśli wyłączymy Twój webhook po wielokrotnych awariach (zobacz Niezawodność webhooków), powyższy przełącznik go nie przywróci. Gdy naprawisz swój punkt końcowy, edytuj webhook i zapisz go ze zmienionym adresem URL (każda zmiana adresu URL powoduje jego ponowne włączenie) lub wywołaj punkt końcowy ponownego włączania przez API — albo poproś o pomoc nasz dział wsparcia, a my włączymy go dla Ciebie.

Podpisane ładunki (weryfikacja, czy webhook faktycznie pochodzi od nas) #

Każdy, kto pozna adres URL Twojego webhooka, może wysłać do niego fałszywe żądanie. Jeśli automatycznie reagujesz na webhooki — aktualizując rozliczenia, tworząc rekordy CRM — włączenie podpisywania pozwoli Ci zweryfikować, czy każde żądanie faktycznie pochodzi od nas.

Podpisywanie jest opcjonalne i domyślnie wyłączone. Włącza się je dla każdego webhooka z osobna, z poziomu widoku edycji danego webhooka (otwórz wiersz zapisanego webhooka).

Włączanie podpisywania #

1. Otwórz webhook (Ustawienia → Integracje → Webhooki → kliknij wiersz swojego webhooka).
2. W sekcji Klucz podpisywania (Signing secret) kliknij Generuj.
3. Skopiuj klucz (zaczyna się od whsec_) i zapisz go w swoim systemie odbiorczym. Traktuj go jak hasło.

W każdej chwili możesz wrócić do tego samego panelu, aby wyświetlić, skopiować, zrotować lub wyłączyć klucz.

Co wysyłamy #

Gdy podpisywanie jest włączone, każde dostarczenie dla tego webhooka zawiera dwa dodatkowe nagłówki HTTP:

Te trzy elementy znajdują się w każdym dostarczeniu, niezależnie od tego, czy jest podpisane, czy nie:

Jak weryfikować #

Podpis to HMAC-SHA256 ciągu znaków <timestamp>.<raw request body>, przy użyciu klucza podpisywania jako klucza szyfrującego.

Weryfikuj na podstawie surowej treści żądania — dokładnie takich bajtów, jakie otrzymałeś. Jeśli Twój framework parsuje JSON i ponownie go serializuje przed sprawdzeniem, bajty mogą ulec zmianie, a podpis nie będzie pasował.

Przykład w Node.js:

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"]; // "v1=<hex>"

  // Reject anything older than 5 minutes so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature.replace("v1=", "")), Buffer.from(expected));
}

Przykład w Pythonie:

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    signature = headers["X-Webhook-Signature"].replace("v1=", "")

    # Reject anything older than 5 minutes so a captured request can't be replayed later.
    if abs(time.time() - int(timestamp)) > 300:
        return False

    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()

    return hmac.compare_digest(signature, expected)

Porównuj podpisy za pomocą funkcji bezpiecznej czasowo (timingSafeEqual / compare_digest), a nie ==. Nic to nie kosztuje, a pozwala uniknąć subtelnej klasy ataków.

Rotacja klucza #

Kliknij Rotuj, aby zastąpić klucz. Zmiana jest natychmiastowa: już następna dostawa jest podpisana wyłącznie nowym kluczem. Jeśli Twój punkt końcowy działa, akceptuj zarówno stary, jak i nowy klucz przez kilka minut, podczas których będziesz wdrażać nowy klucz.

Wyłączenie podpisywania po prostu zatrzymuje wysyłanie nagłówków podpisu.

Ponawianie nieudanych dostaw #

Domyślnie nieudane dostarczenie nie jest ponawiane — jeśli Twój system jest w tym momencie niedostępny, zdarzenie zostaje utracone.

Włącz Ponawianie nieudanych dostarczeń w webhooku (w formularzu tworzenia/edycji), a będziemy podejmować kolejne próby:

Łącznie zajmuje to około 2 godzin i 40 minut, dzięki czemu webhook może przetrwać okno serwisowe lub krótką awarię po Twojej stronie.

Co jest ponawiane: problemy tymczasowe — gdy Twój serwer zwraca błąd 5xx, wystąpił limit czasu (timeout) lub błąd połączenia.

Co nie jest ponawiane: jeśli Twój punkt końcowy odrzuca samo żądanie (jakikolwiek błąd 4xx), nie ponawiamy próby — wysłanie identycznego żądania ponownie wywołałoby tylko identyczne odrzucenie.

Które zdarzenia są ponawiane: każde zdarzenie od 24 września 2026 r. Obejmuje to webhooki tagów (contact_tags_updated), trzy zdarzenia zadań, podsumowanie dzienne, webhook podsumowania, Nowa wiadomość, Zakończono czat, Wstrzymano kontakt, Wznowiono kontakt, Kontakt nie przeszkadzać, Odarchiwizowano kontakt, Niski stan środków, zdarzenia transmisji oraz zdarzenia kontaktu i aktywności: Utworzono kontakt, Zarezerwowano spotkanie, Powiadomiono człowieka, Odpowiedzi, Odczyty, Dostarczenia, Wydano środki i Doładowano środki. Przed tą datą Nowa wiadomość, Zakończono czat, Wstrzymano kontakt, Wznowiono kontakt, Kontakt nie przeszkadzać, Odarchiwizowano kontakt oraz webhook podsumowania były wysyłane jednokrotnie, niezależnie od przełącznika. Każde zdarzenie zawiera X-Webhook-Delivery, więc jedna reguła deduplikacji obejmuje je wszystkie.

Włączaj ponawianie tylko wtedy, gdy Twój punkt końcowy jest idempotentny. Ponawianie oznacza, że to samo zdarzenie może dotrzeć więcej niż raz. Użyj nagłówka X-Webhook-Delivery, aby rozpoznać powtórzenie: pozostaje on taki sam przy każdej próbie dla jednego zdarzenia, więc możesz bezpiecznie zignorować identyfikator, który już obsłużyłeś.

Ponowne próby współpracują z automatycznym wyłączaniem po wielokrotnych awariach (zobacz Niezawodność webhooków) w oczekiwany sposób: licznik awarii zlicza całe dostarczenie dopiero po wykorzystaniu wszystkich ponownych prób — a nie każdą pojedynczą próbę z osobna.

Niezawodność webhooków #

• Your AI Connector wysyła webhooki za pośrednictwem bezpiecznego połączenia (HTTPS). Upewnij się, że podany adres internetowy używa protokołu HTTPS.
• Jeśli Twój system zwróci błąd, dostarczenie zostanie uznane za nieudane.
• Monitoruj czas pracy (uptime) swojego systemu odbierającego, aby uniknąć pominięcia zdarzeń.
• W przypadku krytycznych przepływów pracy włącz Ponawianie nieudanych dostarczeń i rozważ również mechanizm awaryjny (fallback).

Webhooki są wyłączane automatycznie po wielokrotnych awariach. Jeśli adres URL Twojego webhooka wielokrotnie zwraca błędy (około 5 błędów z rzędu lub 3 z rzędu w przypadku błędów konfiguracji), Your AI Connector automatycznie przestaje wysyłać zdarzenia pod ten adres. Aby przywrócić działanie po naprawieniu punktu końcowego: edytuj webhook i zapisz go ze zmienionym adresem URL (każda zmiana adresu URL powoduje jego ponowne włączenie) lub użyj punktu końcowego ponownego włączania przez API — ponowne zapisanie z tym samym adresem URL nie wystarczy. Dział wsparcia może również włączyć go dla Ciebie.

Rozwiązywanie problemów #

Następne kroki #

• Integracja z GoHighLevel — użyj webhooków, aby zintegrować Your AI Connector z GHL.
• Dostęp do API — połącz webhooki z API, aby uzyskać zaawansowaną automatyzację.
• Używanie tagów do oznaczania kontaktów — skonfiguruj tagi, które wyzwalają Twoje webhooki.