Webhook do Zapiera i Make

Dlaczego webhook, a nie gotowa aplikacja w Zapierze

Do kwietnia 2024 istniała droga oficjalna: Facebook Groups API, na którym stał wyzwalacz „New Post in Group” w Zapierze i odpowiedni moduł w Make. Meta ją wyłączyła i nic nie postawiła w zamian. Aplikacja Facebooka w Zapierze nadal istnieje, ale obsługuje strony i reklamy — grupy zniknęły z listy wyzwalaczy i nie wrócą, bo nie ma już interfejsu, na którym mogłyby stanąć.

LeadScanner czyta publiczne grupy i fanpage'e bez konta, tak jak widzi je wylogowany przechodzień, i po każdym skanie może wysłać zdarzenie pod wskazany adres. Z punktu widzenia Zapiera i Make to zwykły webhook przychodzący — czyli dokładnie ten wyzwalacz, którego brakuje. Dalej jest już wszystko, co te narzędzia robią dobrze: wiersz w arkuszu, karta w CRM-ie, wiadomość na Slacku, zadanie dla handlowca.

Kanał webhook jest dostępny w planie Growth i wyższym. Konfiguruje go właściciel albo administrator organizacji, w panelu, w zakładce Powiadomienia → Kanały.

Konfiguracja w Zapierze

W Zapierze załóż nowego Zapa i jako wyzwalacz wybierz aplikację „Webhooks by Zapier”, zdarzenie „Catch Hook”. Zapier pokaże adres, pod którym nasłuchuje — skopiuj go. Nie zamykaj tej karty, wrócisz do niej za chwilę.

W panelu LeadScannera otwórz Powiadomienia → Kanały i dodaj kanał Webhook. Wklej skopiowany adres. Jeżeli chcesz, żeby po drugiej stronie dało się odróżnić Twoje zdarzenia od cudzych, dodaj nagłówek uwierzytelniający: nazwę (na przykład X-Api-Key) i wartość, którą sam wymyślisz.

Zaznacz zdarzenia, które mają wychodzić: „Nowe leady”, „Skan zakończony” albo oba. Do automatyzacji sprzedażowej zwykle wystarczy pierwsze; drugie przydaje się, gdy chcesz logować każdy skan, także pusty. Zapisz kanał i kliknij „Wyślij testowe”.

Wróć do Zapiera i kliknij „Test trigger”. Zapier odbierze testowe zdarzenie i rozłoży je na pola, które od tej chwili możesz mapować w kolejnych krokach: person_name do kolumny z nazwiskiem, post_url do linku, score do priorytetu. Testowe zdarzenie ma pole test ustawione na true i przykładowe dane — nie wpisuj tej osoby do CRM-u, bo nie istnieje.

Konfiguracja w Make

W Make dodaj do scenariusza moduł „Webhooks” → „Custom webhook”, nadaj mu nazwę i skopiuj wygenerowany adres. Make od tej chwili nasłuchuje i czeka na pierwszą wiadomość, żeby z niej odczytać strukturę danych.

Kroki w panelu LeadScannera są te same co dla Zapiera: Powiadomienia → Kanały → Webhook, wklej adres, opcjonalnie dodaj nagłówek uwierzytelniający, wybierz zdarzenia, zapisz i kliknij „Wyślij testowe”.

Po teście Make pokaże, że rozpoznał strukturę. Jeśli tego nie widzisz — na przykład dlatego, że webhook nasłuchiwał już wcześniej i zapamiętał inny kształt — kliknij w module „Redetermine data structure” i wyślij test raz jeszcze. Od tej chwili pola z ładunku są dostępne w każdym kolejnym module scenariusza.

Jedna uwaga praktyczna dla obu narzędzi: zdarzenie „Nowe leady” niesie listę, nie pojedynczego leada. W Make rozbij ją iteratorem, w Zapierze użyj kroku „Looping by Zapier” — albo mapuj tylko pierwszy element, jeżeli i tak reagujesz na całą paczkę naraz.

Zdarzenie new_leads: co przychodzi

Każde zdarzenie to jedno żądanie POST z ciałem w formacie JSON. Na wierzchu stoi zawsze ten sam zestaw pól: event — nazwa zdarzenia, tu new_leads; version — numer wersji formatu, dziś 1; organization_id — identyfikator Twojej organizacji; sent_at — czas wysłania w ISO 8601; subject — jednozdaniowy tytuł, ten sam, który idzie w temacie e-maila; leads_count — liczba leadów w paczce; leads — lista leadów.

Każdy element listy leads ma: person_name — imię i nazwisko autora wpisu, tak jak widnieje na Facebooku; score — ocena od 0 do 100, im wyżej, tym pewniejsze zapytanie; excerpt — fragment posta albo komentarza, w którym padło pytanie; post_url — link do wpisu; profile_url — link do profilu autora, jeśli był widoczny, inaczej null; rationale — jedno zdanie o tym, dlaczego ten wpis został uznany za lead; source_name — nazwa grupy albo strony, w której padł.

Testowa wysyłka ma dokładnie ten kształt, tylko z przykładowymi danymi i dodatkowym polem test ustawionym na true. To najprostszy sposób, żeby zobaczyć pełny przykład: kliknij „Wyślij testowe” i obejrzyj w Zapierze albo w Make, co przyszło.

Zdarzenie scan_finished: to samo plus skan

Zdarzenie scan_finished niesie wszystkie pola opisane wyżej — z listą leads znalezionych w tym skanie, która może być pusta — i dodatkowo obiekt scan. W nim: id — identyfikator skanu; source_id, source_name i source_url — które źródło było sprawdzane; status — jak się skończył; mode — tryb, słowa kluczowe albo AI; scheduled_slot — slot harmonogramu, do którego skan należał; started_at i finished_at — czas rozpoczęcia i zakończenia; points_spent — ile punktów kosztował; leads_found — ile leadów znalazł; error i error_code — opis i kod błędu, gdy skan padł, w przeciwnym razie null.

Do tego coverage, czyli rozliczenie z tego, co skan obejrzał: posts_seen i comments_seen — ile wpisów i komentarzy przeczytał; posts_suppressed — ile wpisów pominął, bo ich autorzy poprosili o usunięcie swoich danych; posts_stale i comments_stale — ile było starszych niż okno świeżości; posts_unchanged i comments_unchanged — ile już znał z poprzedniego wejścia i nie oceniał ponownie; graded — ile fragmentów trafiło do oceny; leads — ile z nich zostało leadami; rejected — lista par reason i count, czyli z jakich powodów i ile odpadło.

Liczby w coverage zawsze się sumują: graded to świeże wpisy i komentarze po odjęciu starych i już znanych, a leads plus suma rejected daje graded. Jeśli budujesz na tym dashboard, możesz na tych dwóch tożsamościach polegać.

Powody w rejected są zawsze z tej samej listy: no_keyword (żadne słowo kluczowe nie padło), no_intent (nie da się orzec, czy autor czegoś szuka), not_in_market (mówi językiem branży, ale nie kupuje — doradza, relacjonuje, sprzedaje), outside_offer (kupuje, ale nie to albo nie tam, gdzie działasz), excluded (pyta dokładnie o to, czego nie robisz), below_threshold (pasuje, ale za słabo jak na próg), ungraded (model odpowiedział w kształcie, którego nie dało się odczytać). Trzymaj je jako słownik, a nie mapuj na oko.

Podpis HMAC i to, co zamiast niego

Jeżeli w kanale ustawisz sekret, każde żądanie dostanie dwa nagłówki: X-LeadScanner-Timestamp z czasem podpisu w sekundach uniksowych i X-LeadScanner-Signature z wartością v1=<hex>, gdzie hex to HMAC-SHA256 z ciągu „<timestamp>.<ciało>” liczony Twoim sekretem. Odbiorca liczy to samo po swojej stronie i porównuje; podpis starszy niż pięć minut odrzuca. Dzięki temu nikt, kto zna sam adres, nie podszyje się pod LeadScanner ani nie odtworzy przechwyconego żądania tydzień później.

Bez sekretu nagłówków podpisu nie ma — zdarzenie idzie bez podpisu, tak jak większość integracji no-code. Zapier i Make nie liczą HMAC bez dodatkowego kroku z kodem, więc dla nich prostszą i wystarczającą ochroną jest nagłówek uwierzytelniający z panelu: po stronie automatyzacji dodaj filtr, który przepuszcza tylko żądania z tą nazwą i tą wartością.

Dwie reguły, których nie da się wyłączyć: adres musi być publicznym HTTPS — zwykłe http ani adres w sieci lokalnej nie przejdą — a przekierowania są odrzucane. Jeśli Twój serwer odpowiada 301 albo 302, dostawa kończy się błędem, a nie cichym przejściem pod inny adres, bo pod innym adresem podpis i nagłówek uwierzytelniający trafiłyby nie tam, gdzie miały.

Gdy dostawa się nie uda

Odpowiedź inna niż 2xx, przekroczenie czasu albo zerwane połączenie oznaczają nieudaną próbę. Nie kończymy na niej: zdarzenie wysyłamy ponownie trzy razy, z rosnącymi odstępami — pierwsza powtórka po pół minucie, ostatnia po kilku. To wystarcza, żeby przeczekać restart serwera albo chwilowy limit po stronie Zapiera, a jednocześnie powiadomienie, które w końcu dojdzie, jest jeszcze powiadomieniem, nie kroniką.

Każda próba — udana czy nie — jest widoczna w panelu, pod kanałem, z czasem, kodem odpowiedzi i powodem błędu. Jeśli po czterech próbach zdarzenie nie doszło, zostaje na tej liście jako nieudane i tam należy zacząć szukać: zwykle chodzi o adres Zapa, który przestał istnieć, albo o scenariusz w Make, który ktoś wyłączył.

API, szablony i MCP

Publiczne API v1 stoi pod /api/v1, dokumentacja pod /api/v1/docs. Klucz zaczynający się od ls_ tworzysz w panelu w Ustawienia → Integracje i wysyłasz w nagłówku Authorization: Bearer. API jest na każdym planie, limit to 600 żądań na godzinę na organizację.

Gotowe szablony pod webhook leżą w katalogu integrations/ repozytorium produktu: przepis krok po kroku dla Zapiera, blueprint JSON do wczytania w Make przez Import Blueprint i workflow JSON do wczytania w n8n przez Import from File. Wszystkie trzy rozbijają listę leads na pojedyncze leady, przepuszczają tylko score co najmniej 60, pomijają zdarzenia testowe i zapisują lead jako wiersz w Google Sheets.

Serwer MCP pod /mcp przyjmuje ten sam klucz ls_, dla Claude i innych asystentów AI. Narzędzia to list_leads, get_lead, set_lead_status, set_lead_feedback, get_reply_draft, list_campaigns, list_sources, create_source, update_source.

Alerty e-mail, Slack, SMS i webhook pokazują teraz wiek posta. W ładunku webhooka lead ma published_at, czyli datę posta w ISO 8601 albo null, oraz age_minutes, czyli minuty w chwili wysyłki albo null. Wersja ładunku zostaje 1, bo dołożenie pola nie tworzy nowej wersji: mapuj po nazwach.