Webhooki
Wysyłaj zakupy, odnowienia, zapisy i inne zdarzenia na własny adres: dodaj webhook, przetestuj go, zweryfikuj podpis, sprawdzaj stan wysyłek, wysyłaj ponownie, wstrzymuj i usuwaj.
Webhook wysyła wiadomość na Twój adres za każdym razem, gdy na Twoim koncie zajdzie wybrane zdarzenie, na przykład nowy zakup. Po wykonaniu tych kroków masz aktywny webhook, sekret podpisu do weryfikacji jego wiadomości i miejsce, w którym obserwujesz wysyłki. Webhooki są częścią każdego aktualnego planu Zanfii.
Dodaj webhook
Otwórz Webhooki
W menu otwórz Automatyzacje → Webhooki (/workflows/webhooks) i kliknij Dodaj webhook.
Otwiera się pełnoekranowy formularz Dodaj webhook (/workflows/webhooks/new).
Wpisz adres
Wklej adres swojego endpointu w pole Adres URL webhooka. Musi to być pełny adres URL, na
przykład https://domain.com/hook; inna wartość zostaje odrzucona, zanim formularz da się zapisać
lub przetestować.
Dodaj nagłówki lub basic auth (opcjonalnie)
Rozwiń Własne nagłówki i basic auth. Dodaj nagłówek dodaje klucz i wartość wysyłane z każdą wiadomością. Dane basic auth to pola Nazwa użytkownika i Hasło. „Dane są przechowywane w postaci zaszyfrowanej i nie będą ponownie wyświetlane”: przy późniejszej edycji webhooka wartości nagłówków są oznaczone jako niezmienione i wpisujesz je tylko po to, by je zastąpić.
Wybierz zdarzenia
W sekcji Które zdarzenia mamy wysyłać? zaznacz co najmniej jedno zdarzenie. Zdarzenia są podzielone na grupy Sprzedaż i koszyk, Subskrypcje i dostęp, Klienci oraz Kamienie milowe i polecenia; pełna lista jest w tabeli poniżej.
Wyślij test
W sekcji Przetestuj adres webhooka wybierz zdarzenie i kliknij Wyślij test. Ciemne pole
pokazuje dokładną treść wysyłanej wiadomości. Zielony komunikat „Wysłano testowe zdarzenie -
endpoint odpowiedział 200” oznacza, że Twój endpoint odpowiedział; odpowiedź spoza zakresu 200
jest pokazywana jako ostrzeżenie, a „Testowa wysyłka nie powiodła się - nie udało się połączyć z
adresem” oznacza, że adres w ogóle nie odpowiedział. Wiadomości testowe zawierają "test": true.
Zapisz i skopiuj sekret podpisu
Zostaw włączony przełącznik Aktywny i kliknij Zapisz webhook. Okno Sekret podpisu
Twojego webhooka pokazuje kod zaczynający się od whsec_. Skopiuj go i kliknij OK. Wracasz
na listę; nowy wiersz pokazuje znacznik POST, adres, zdarzenia i włączony przełącznik
Aktywny.
Warto wiedzieć
Sekret podpisu nie przepada, jeśli nie zostanie skopiowany od razu. Otwórz webhook, kliknij Edytuj i użyj przycisku Pokaż obok pola Sekret podpisu. Wygeneruj nowy tworzy nowy sekret: „Obecny sekret natychmiast przestanie działać. Wysyłki będą kontynuowane, ale Twój serwer musi otrzymać nowy sekret, aby je weryfikować.”
Zdarzenia, które możesz subskrybować
| Grupa | Zdarzenie w formularzu | Wartość event w wiadomości |
|---|---|---|
| Sprzedaż i koszyk | Nowy zakup | product.ProductPurchased |
| Darmowy zapis zakończony | product.FreeSignupCompleted | |
| Formularz przesłany | form.FormSubmitted | |
| Utworzono zamówienie (również przy nieudanej płatności) | product.OrderCreated | |
| Zwrot zamówienia | product.OrderRefunded | |
| Porzucony koszyk | checkout.CheckoutAbandoned | |
| Subskrypcje i dostęp | Koniec subskrypcji | product.ProductSubscriptionEnd |
| Odnowienie subskrypcji | product.ProductSubscriptionRenewed | |
| Odnowienie okresu dostępu | product.ProductAccessRenewed | |
| Koniec okresu dostępu | product.ProductAccessPeriodEnd | |
| 14 dni, 7 dni, 3 dni, 1 dzień do końca okresu dostępu | product.ProductAccessPeriodEndingIn14Days, …In7Days, …In3Days, …In1Day | |
| Klienci | Zapis do newslettera | client.SubscribedToAudience |
| Dodano tag klientowi | client.TagAdded | |
| Subskrybent ucichł | client.Unengaged | |
| Przesłano opinię | testimonial.TestimonialSubmitted | |
| Zaimportowano klienta | product.ClientImported | |
| Klient zarchiwizowany w produkcie | product.ProductClientArchived | |
| Klient usunięty z produktu | product.ProductClientRemoved | |
| Kamienie milowe i polecenia | Kurs ukończony | course.CourseCompleted |
| Zweryfikowane polecenie | productReferrals.ValidSubscriberFromReferral | |
| Nagroda za polecenia zdobyta | productReferrals.ReferralRewardEarned |
Powiadomienie na 14 dni przed końcem jest wysyłane tylko dla dostępów trwających co najmniej 3 miesiące.
Jak wygląda wysyłka
Każda wysyłka to żądanie HTTP POST z treścią JSON i poniższymi nagłówkami, do których dochodzą skonfigurowane przez Ciebie własne nagłówki i basic auth:
| Nagłówek | Wartość |
|---|---|
X-Zanfia-Event | Nazwa zdarzenia, dzięki czemu możesz kierować wiadomości bez parsowania treści |
X-Zanfia-Signature | t=[czas unix],v1=[podpis], opis poniżej |
X-Zanfia-Test | true, tylko w wiadomościach testowych wysyłanych z panelu |
Treść ma zawsze tę samą kopertę. Klucze wymienione w data są zawsze obecne i mają wartość null, gdy zdarzenie nie niesie dla nich wartości; zdarzenie może dodać własne klucze (przy zakupie: productName, paymentType, quantity, price).
{
"apiVersion": "2026-07-13",
"event": "product.ProductPurchased",
"occurredAt": "2026-09-30T10:00:00.000Z",
"workspaceId": "identyfikator Twojego konta",
"data": {
"clientId": "cli_4f81c92a7b3d",
"clientEmail": "anna.novak@example.com",
"clientFirstName": "Anna",
"clientLastName": "Novak",
"clientName": "Anna Novak",
"clientPhoneNumber": "+48600100200",
"clientCustomFields": { "city": "Kraków", "company_size": 12 },
"clientAddress": { "street": "Mokotowska 71", "postalCode": "00-530", "city": "Warszawa" },
"productId": "prod_8c31a2f4d95e",
"priceId": "price_5e92c7d1a48b",
"orderId": "35e479ee-d456-4ee9-a5da-e7ff8109ffcc",
"checkoutId": "chk_1f83b6a92c4d",
"orderTotalAmount": 199,
"orderNetAmount": 161.79,
"consents": [{ "name": "marketing", "value": true }],
"utmSource": "facebook",
"utmMedium": "cpc",
"utmCampaign": "summer-launch",
"utmTerm": null,
"utmContent": null,
"productName": "Kurs online",
"paymentType": "one_time",
"quantity": 1,
"price": { "amount": 19900, "currency": "pln", "accessPeriod": null }
}
}
Kwoty mają różne jednostki, zależnie od pola i zdarzenia. orderTotalAmount i orderNetAmount, gdy są wypełnione, są zawsze w złotych (przy innej walucie w jej jednostkach głównych).
| Pole | Zdarzenia | Jednostka | Przykład |
|---|---|---|---|
orderTotalAmount | każde zdarzenie z orderId | złote | 199 to 199 zł |
orderNetAmount | każde zdarzenie z orderId | złote, bez VAT według stawki z faktury produktu | 161.79 to 161,79 zł |
price.amount | Nowy zakup, Utworzono zamówienie (również przy nieudanej płatności), Zaimportowano klienta, Zweryfikowane polecenie | grosze | 19900 to 199 zł |
price.amount | Odnowienie subskrypcji, Odnowienie okresu dostępu | złote | 199 to 199 zł |
price.amount | Koniec subskrypcji, Koniec okresu dostępu | grosze albo złote, zależnie od sposobu płatności klienta | nie licz z tego pola |
amountMinor | Zwrot zamówienia | grosze | 19900 to 199 zł |
refund.amount | Klient zarchiwizowany w produkcie | złote | 199 to 199 zł |
Waluta jest w polu currency obok kwoty, na przykład pln. price ma wartość null przy darmowym lub w pełni obniżonym zakupie, w powiadomieniach przed końcem okresu dostępu i przy imporcie bez płatności, a refund ma wartość null, gdy archiwizacja nie wiązała się ze zwrotem. Jeśli potrzebujesz tylko kwoty zapłaconej za zamówienie, najprościej czytać orderTotalAmount.
Zamówienie z produktem dodatkowym wysyła jeden Nowy zakup bez isAdditionalProduct, w którym price.amount to kwota całego zamówienia razem z produktami dodatkowymi, a do tego osobny Nowy zakup dla każdego produktu dodatkowego, z "isAdditionalProduct": true. Nie sumuj więc price.amount po orderId, bo produkty dodatkowe policzysz dwa razy. Kwotę zamówienia bierz z price.amount głównego zdarzenia (w groszach) albo z orderTotalAmount (w złotych).
Pole podglądu w edytorze pokazuje treść dla zdarzenia, które wybierzesz, więc traktuj je jako źródło wiedzy o dodatkowych kluczach każdego zdarzenia.
Telefon, pola własne i adres
Każde zdarzenie dotyczące klienta dodaje jego dane w takiej postaci, w jakiej są zapisane w Zanfii w chwili wysyłki. Dzięki temu dociera też wartość zapisana już po zdarzeniu, także przy zdarzeniach, które same jej nie niosą, na przykład Dodano tag klientowi, Zapis do newslettera czy Formularz przesłany:
clientPhoneNumber: numer telefonu z karty klienta, dokładnie tak, jak go zapisano;null, gdy klient go nie ma.clientCustomFields: wartości pól własnych klienta, pod kluczem każdego pola (na przykładcity). Klucza nie ma, gdy klient nie ma żadnych wartości.
Zdarzenie bez klienta ma clientPhoneNumber równe null i nie ma clientCustomFields. Zakup ma też phoneNumber wpisany przez kupującego w koszyku.
Nowy zakup i Utworzono zamówienie (również przy nieudanej płatności) mają też clientAddress: adres, który kupujący podał w koszyku (street, postalCode, city), odczytany z zamówienia w chwili wysyłki, albo null, gdy go nie podał. Możesz go użyć na przykład do wysyłki prezentu przez Make.
Przy tej treści zdarzenia historia wywołań w panelu pokazuje clientPhoneNumber jako null i pomija clientCustomFields oraz clientAddress; Twój adres dostaje prawdziwe wartości.
Zweryfikuj podpis
Każda wysyłka zawiera nagłówek X-Zanfia-Signature: t=[czas unix],v1=[podpis]. Podpis to HMAC-SHA256, zapisany szesnastkowo, z tekstu [t].[surowe body] (wartość t, kropka, a potem treść żądania dokładnie w otrzymanej postaci), obliczony Twoim sekretem podpisu. Na swoim serwerze:
- Odczytaj
tiv1z nagłówka. - Oblicz HMAC-SHA256 z wartości
t, kropki i surowej treści żądania, używając sekretuwhsec_jako klucza. - Porównaj wynik z
v1porównaniem w stałym czasie i odrzuć żądanie, jeśli się różnią.
Obliczaj podpis z surowej treści, przed parsowaniem JSON; treść zserializowana ponownie daje inny podpis.
Monitoruj, wysyłaj ponownie, wstrzymuj i usuwaj
Lista pod adresem /workflows/webhooks ma cztery kolumny: Endpoint, Zdarzenia, Stan i Aktywny.
| Co widzisz | Znaczenie |
|---|---|
| Działa poprawnie, z czasem ostatniego wywołania | Ostatnie wysyłki się powiodły. |
| „[n]/[m] ostatnich wywołań nieudanych” | Część ostatnich wysyłek się nie powiodła. |
| Brak wywołań | Nic jeszcze nie zostało wysłane. Wiadomości testowe z edytora się nie liczą. |
| Wstrzymany automatycznie obok przełącznika | „Wstrzymany automatycznie po 15 nieudanych wysyłkach z rzędu. Napraw endpoint i włącz webhook ponownie.” |
Kliknij wiersz, aby otworzyć okno Szczegóły webhooka: adres, stan, zdarzenia oraz Ostatnie wywołania z czasem, statusem i odpowiedzią. Strzałka ponownej wysyłki przy wywołaniu wysyła to zdarzenie jeszcze raz z aktualnymi ustawieniami webhooka („Zdarzenie wysłane ponownie - endpoint odpowiedział 200”). Przyciski na dole to Usuń („Usunąć ten webhook?”), Wyślij test i Edytuj.
Aby wstrzymać webhook bez usuwania, wyłącz jego przełącznik Aktywny na liście; przestaje otrzymywać zdarzenia do czasu ponownego włączenia.
Webhooki w automatyzacjach
Jeśli któraś z Twoich automatyzacji zawiera akcję webhook, jej adres pojawia się w drugiej tabeli, Używane w automatyzacjach, razem z automatyzacjami, które go wywołują, oraz tym samym stanem i historią wywołań. Te adresy edytuje się w samej automatyzacji, nie tutaj. Webhook w automatyzacji z własną treścią może wysłać zapisany telefon klienta wartością phoneNumber, jedno pole własne wartością custom.[klucz pola] (na przykład custom.city), wszystkie naraz wartością customFields, a adres z koszyka zamówienia wartością clientAddress; wartość, której klient nie ma, idzie jako null. O automatyzacjach przeczytasz w artykule Zbuduj automatyzację.
Czy ten artykuł był pomocny?

