Integracje

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.

8 min czytaniaOstatnia aktualizacja: 29 paź 2026

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

1

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).

2

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ć.

3

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ć.

4

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.

5

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.

6

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ć

GrupaZdarzenie w formularzuWartość event w wiadomości
Sprzedaż i koszykNowy zakupproduct.ProductPurchased
Darmowy zapis zakończonyproduct.FreeSignupCompleted
Formularz przesłanyform.FormSubmitted
Utworzono zamówienie (również przy nieudanej płatności)product.OrderCreated
Zwrot zamówieniaproduct.OrderRefunded
Porzucony koszykcheckout.CheckoutAbandoned
Subskrypcje i dostępKoniec subskrypcjiproduct.ProductSubscriptionEnd
Odnowienie subskrypcjiproduct.ProductSubscriptionRenewed
Odnowienie okresu dostępuproduct.ProductAccessRenewed
Koniec okresu dostępuproduct.ProductAccessPeriodEnd
14 dni, 7 dni, 3 dni, 1 dzień do końca okresu dostępuproduct.ProductAccessPeriodEndingIn14Days, …In7Days, …In3Days, …In1Day
KlienciZapis do newsletteraclient.SubscribedToAudience
Dodano tag klientowiclient.TagAdded
Subskrybent ucichłclient.Unengaged
Przesłano opiniętestimonial.TestimonialSubmitted
Zaimportowano klientaproduct.ClientImported
Klient zarchiwizowany w produkcieproduct.ProductClientArchived
Klient usunięty z produktuproduct.ProductClientRemoved
Kamienie milowe i poleceniaKurs ukończonycourse.CourseCompleted
Zweryfikowane polecenieproductReferrals.ValidSubscriberFromReferral
Nagroda za polecenia zdobytaproductReferrals.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łówekWartość
X-Zanfia-EventNazwa zdarzenia, dzięki czemu możesz kierować wiadomości bez parsowania treści
X-Zanfia-Signaturet=[czas unix],v1=[podpis], opis poniżej
X-Zanfia-Testtrue, 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).

PoleZdarzeniaJednostkaPrzykład
orderTotalAmountkażde zdarzenie z orderIdzłote199 to 199 zł
orderNetAmountkażde zdarzenie z orderIdzłote, bez VAT według stawki z faktury produktu161.79 to 161,79 zł
price.amountNowy zakup, Utworzono zamówienie (również przy nieudanej płatności), Zaimportowano klienta, Zweryfikowane poleceniegrosze19900 to 199 zł
price.amountOdnowienie subskrypcji, Odnowienie okresu dostępuzłote199 to 199 zł
price.amountKoniec subskrypcji, Koniec okresu dostępugrosze albo złote, zależnie od sposobu płatności klientanie licz z tego pola
amountMinorZwrot zamówieniagrosze19900 to 199 zł
refund.amountKlient zarchiwizowany w produkciezłote199 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ład city). 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:

  1. Odczytaj t i v1 z nagłówka.
  2. Oblicz HMAC-SHA256 z wartości t, kropki i surowej treści żądania, używając sekretu whsec_ jako klucza.
  3. Porównaj wynik z v1 poró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 widziszZnaczenie
Działa poprawnie, z czasem ostatniego wywołaniaOstatnie 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?

Powiązane artykuły

Coś się nie zgadza? Napisz do nas na support@zanfia.com.