> ## Documentation Index
> Fetch the complete documentation index at: https://pomoc.wenetasystent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks (Make, Zapier, n8n)

> Wysyłaj dane z rozmów Asystenta AI do dowolnego systemu — z gotowymi przykładami integracji w Make.com, Zapier i n8n.

## Co to jest webhook

Webhook to **adres URL Twojego systemu** (CRM, Slack, Notion, Google Sheets, własna aplikacja), pod który Asystent AI wysyła dane za każdym razem, gdy klient zostawi swoje dane kontaktowe podczas rozmowy. Dzięki temu nowe leady mogą trafiać do Twoich workflow w czasie rzeczywistym, bez ręcznego przepisywania.

<Note>
  Webhook wysyłany jest po zdarzeniu **`lead.captured`** — czyli wtedy, gdy klient w rozmowie z chatbotem poda swoje dane kontaktowe (imię, e-mail, telefon).
</Note>

## Jak skonfigurować webhook

<Steps>
  <Step title="Wygeneruj URL w docelowym narzędziu">
    W Make.com, Zapier, n8n lub własnym backendzie utwórz endpoint, który będzie odbierał żądania POST. Skopiuj jego adres (musi zaczynać się od `https://`). Przykłady poniżej w sekcji **Gotowe scenariusze**.
  </Step>

  <Step title="Otwórz Ustawienia → Integracje">
    Zaloguj się do [app.wenetasystent.ai](https://app.wenetasystent.ai). W menu po lewej kliknij **koło zębate** (Ustawienia), a następnie zakładkę **Integracje**.
  </Step>

  <Step title="Wklej URL w karcie „Przekazywanie zapytań ofertowych”">
    W polu **Adres URL webhooka** wklej skopiowany endpoint i kliknij **Zapisz**.
  </Step>

  <Step title="Wyślij testowy payload">
    Kliknij **Wyślij test**. Asystent AI prześle syntetyczny payload (kontakt „Jan Testowy") pod podany adres. Sprawdź, czy Twój workflow odebrał dane.
  </Step>

  <Step title="Włącz integrację suwakiem">
    Po udanym teście włącz suwak w prawym górnym rogu karty. Od tego momentu każdy nowy lead będzie wysyłany automatycznie.
  </Step>
</Steps>

<Warning>
  Wymagany jest protokół **HTTPS**. Adresy `http://` zostaną odrzucone przez panel.
</Warning>

## Struktura wysyłanych danych

Każde żądanie to `POST` z nagłówkami i ciałem JSON.

### Nagłówki HTTP

| Nagłówek               | Wartość                                                         |
| ---------------------- | --------------------------------------------------------------- |
| `Content-Type`         | `application/json`                                              |
| `X-Asystent-Event`     | `lead.captured`                                                 |
| `X-Asystent-Signature` | `sha256=<HMAC_SHA256_payloadu>` (do weryfikacji autentyczności) |

### Payload

```json theme={null}
{
  "event": "lead.captured",
  "event_id": "evt_V1StGXR8_Z5jdHi6B-myT",
  "api_version": "2026-03",
  "timestamp": "2026-04-28T09:14:33.218Z",
  "data": {
    "contact": {
      "first_name": "Jan",
      "last_name": "Kowalski",
      "email": "jan@firma.pl",
      "phone": "+48123456789"
    },
    "summary": "Klient zainteresowany wdrożeniem dla 20-osobowego zespołu, budżet do 5000 zł/mc.",
    "transcript": [
      { "role": "assistant", "content": "Cześć! W czym mogę pomóc?", "timestamp": 1745832823000 },
      { "role": "user",      "content": "Szukam chatbota dla mojej firmy.", "timestamp": 1745832867000 }
    ],
    "widget_id": "widget_chat_id",
    "consents": [
      { "id": "rodo", "label": "Zgoda RODO", "required": true, "enabled": true }
    ]
  }
}
```

### Pola payloadu

| Pole              | Typ               | Opis                                                                         |
| ----------------- | ----------------- | ---------------------------------------------------------------------------- |
| `event`           | string            | Zawsze `lead.captured`                                                       |
| `event_id`        | string            | Unikalne ID zdarzenia (`evt_<nanoid>`) — do deduplikacji po stronie odbiorcy |
| `api_version`     | string            | Wersja schematu payloadu (obecnie `2026-03`)                                 |
| `timestamp`       | string (ISO 8601) | Moment wysłania webhooka                                                     |
| `data.contact`    | object            | Imię, nazwisko, e-mail, telefon klienta                                      |
| `data.summary`    | string \| null    | Streszczenie rozmowy wygenerowane przez AI                                   |
| `data.transcript` | array             | Pełny zapis rozmowy (rola, treść, timestamp ms)                              |
| `data.widget_id`  | string            | ID rozmowy w panelu Asystent AI                                              |
| `data.consents`   | array             | Lista zgód (np. RODO) zaakceptowanych przez klienta                          |

<Tip>
  Dziennik dostarczeń (sukcesy, błędy, status HTTP) jest zapisywany po stronie Asystent AI — w razie problemów napisz na [pomoc@wenetasystent.ai](mailto:pomoc@wenetasystent.ai), pomożemy zdiagnozować.
</Tip>

## Niezawodność i bezpieczeństwo

* **Retry**: jeśli Twój endpoint zwróci błąd (status ≥ 400) lub nie odpowie w 10 sekund, system ponowi próbę — łącznie do **3 prób** z exponential backoff
* **Deduplikacja**: użyj `event_id` po stronie odbiorcy, żeby nie zaksięgować tego samego leada dwa razy
* **Weryfikacja HMAC** (opcjonalna, zalecana dla custom backendów): policz HMAC-SHA256 z ciała żądania używając swojego sekretu (kontakt z supportem) i porównaj z nagłówkiem `X-Asystent-Signature`. Make.com / Zapier / n8n mają wbudowane narzędzia do tego (sekcja niżej).

***

## Gotowe scenariusze

Poniższe instrukcje pokazują **najszybszą drogę** do podpięcia webhooka w trzech popularnych narzędziach.

### Make.com (dawniej Integromat)

<Steps>
  <Step title="Utwórz nowy scenariusz">
    Zaloguj się do [make.com](https://www.make.com/) i kliknij **Create a new scenario**.
  </Step>

  <Step title="Dodaj moduł „Webhooks → Custom webhook”">
    Wyszukaj moduł **Webhooks**, wybierz **Custom webhook** i kliknij **Add**, aby utworzyć nowy webhook (nadaj mu nazwę, np. „Asystent AI — leady"). Make wygeneruje unikalny URL — **skopiuj go**.
  </Step>

  <Step title="Wklej URL w panelu Asystent AI">
    W **Ustawienia → Integracje** wklej URL w polu **Adres URL webhooka** i zapisz.
  </Step>

  <Step title="Wyślij test z panelu Asystent AI">
    Kliknij **Wyślij test** w panelu. Wróć do Make i kliknij **Re-determine data structure** lub **Run once** — Make rozpozna strukturę pól (`data.contact.email`, `data.summary` itd.) i będzie je można mapować w kolejnych modułach.
  </Step>

  <Step title="Dodaj kolejne moduły workflow">
    Po module webhooka dodaj np. **HubSpot — Create a contact**, **Google Sheets — Add a row** lub **Slack — Send a message**. Mapuj pola z payloadu do parametrów modułów.
  </Step>

  <Step title="Włącz scenariusz">
    Kliknij **Run** i przełącz scheduler w pozycję **ON** w lewym dolnym rogu edytora.
  </Step>
</Steps>

<Tip>
  Aby weryfikować HMAC w Make: dodaj moduł **Tools → Compose a string** lub **Crypto → Create HMAC** z ustawieniami `algorithm: SHA-256`, `key: <Twój sekret>`, `data: <body webhooka>`, a następnie porównaj z nagłówkiem `X-Asystent-Signature` w **Router** lub **Filter**.
</Tip>

### Zapier

<Steps>
  <Step title="Utwórz nowego Zapa">
    W [zapier.com](https://zapier.com/) kliknij **Create Zap**.
  </Step>

  <Step title="Trigger: Webhooks by Zapier → Catch Hook">
    Jako trigger wybierz **Webhooks by Zapier** (wymaga planu Starter+). Akcja: **Catch Hook**. Zapier wygeneruje **Custom Webhook URL** — skopiuj go.
  </Step>

  <Step title="Wklej URL w panelu Asystent AI i wyślij test">
    W Asystent AI wklej URL w **Ustawienia → Integracje**, zapisz, kliknij **Wyślij test**. Wróć do Zapiera i kliknij **Test trigger** — zobaczysz strukturę pól z payloadu (`data__contact__email`, `data__summary`).
  </Step>

  <Step title="Dodaj akcję">
    Wybierz akcję — np. **Google Sheets → Create Spreadsheet Row**, **HubSpot → Create or Update Contact**, **Pipedrive → Create Lead**, **Slack → Send Channel Message**. Zmapuj pola z triggera do parametrów akcji.
  </Step>

  <Step title="Publikuj Zapa">
    Kliknij **Publish**. Od teraz każdy webhook z Asystenta AI uruchomi Twój workflow.
  </Step>
</Steps>

<Note>
  Zapier po stronie triggera „Catch Hook" nie weryfikuje HMAC out-of-the-box. Jeśli potrzebujesz weryfikacji autentyczności, dodaj krok **Code by Zapier (Python)** który policzy HMAC-SHA256 i zwróci `Continue` / `Stop` przez **Filter by Zapier**.
</Note>

### n8n

<Steps>
  <Step title="Utwórz nowy workflow">
    W swojej instancji n8n (cloud lub self-hosted) kliknij **New workflow**.
  </Step>

  <Step title="Dodaj node Webhook">
    Wyszukaj node **Webhook**. Ustaw:

    * **HTTP Method**: `POST`
    * **Path**: dowolna nazwa, np. `asystent-leads`
    * **Authentication**: `None` (HMAC zweryfikujesz w kolejnym node)
    * **Response Mode**: `Last node` (lub `Immediately` z kodem 200)

    Skopiuj **Production URL** wygenerowany przez n8n.
  </Step>

  <Step title="Wklej URL w panelu Asystent AI">
    Wklej Production URL w **Ustawienia → Integracje** i zapisz. Aktywuj workflow w n8n (przełącznik **Active** w prawym górnym rogu).
  </Step>

  <Step title="Wyślij test i podejrzyj payload">
    Kliknij **Wyślij test** w Asystent AI. W n8n otwórz node Webhook → zakładka **Executions** — zobaczysz odebrany payload i wszystkie nagłówki.
  </Step>

  <Step title="Dodaj kolejne nodes">
    Po node Webhook dodaj np. **HubSpot**, **Google Sheets**, **Slack**, **Postgres** lub **HTTP Request** do własnego API. Mapuj pola wyrażeniami `{{$json.data.contact.email}}`, `{{$json.data.summary}}` itd.
  </Step>
</Steps>

<Tip>
  **Weryfikacja HMAC w n8n**: po node Webhook dodaj node **Crypto** z operacją `HMAC`, algorytm `SHA256`, kluczem ustawionym na Twój sekret i wartością `{{$json.body}}` (raw body). Następnie node **IF** porównaj wynik z `{{$json.headers["x-asystent-signature"]}}` (po usunięciu prefiksu `sha256=`). Tylko zgodne żądania przepuszczaj dalej.
</Tip>

***

## Rozwiązywanie problemów

<AccordionGroup>
  <Accordion title="„Wyślij test” zwraca błąd HTTP">
    * Status `4xx` — Twój endpoint odrzucił żądanie. Sprawdź logi po stronie odbiorcy (Make/Zapier/n8n). Najczęstsze powody: nieaktywny scenariusz, brak ustawienia `Catch Hook` na nasłuchiwanie, błąd w mapowaniu pól.
    * Status `5xx` — błąd po stronie odbiorcy. Spróbuj jeszcze raz; jeśli problem się powtarza, sprawdź dostępność endpointu.
    * **Brak odpowiedzi / timeout** — endpoint nie odpowiedział w 10 sekund. Skróć logikę po stronie odbiorcy lub przekaż dane do kolejki i odpowiedz natychmiast.
  </Accordion>

  <Accordion title="Webhook nie wysyła się przy prawdziwym leadzie">
    * Sprawdź, czy suwak integracji jest **włączony** (prawy górny róg karty „Przekazywanie zapytań ofertowych").
    * Upewnij się, że klient faktycznie zostawił dane kontaktowe podczas rozmowy — webhook startuje dopiero po uzupełnieniu kontaktu.
    * Jeśli używasz Make.com: scenariusz musi być w stanie **ON** (nie tylko zapisany).
  </Accordion>

  <Accordion title="Otrzymuję ten sam lead kilka razy">
    To efekt mechanizmu **retry** — jeśli Twój endpoint odpowie błędem lub timeoutem, system ponowi próbę. Użyj pola `event_id` jako klucza deduplikacji w bazie / arkuszu / CRM-ie. Zwracaj `2xx` jak najszybciej (np. od razu po przyjęciu payloadu), a logikę przenieś do kolejki.
  </Accordion>

  <Accordion title="Chcę używać webhooków razem z integracją Firmao CRM">
    Tak, można równolegle. Webhook (np. do n8n) i bezpośrednia integracja [Firmao CRM](/integrations/firmao) działają niezależnie. Każda rozmowa, w której klient zostawi dane, uruchomi obie integracje.
  </Accordion>
</AccordionGroup>