Webhook to powiadomienie, które Zanfia wysyła do Twojego systemu w momencie, gdy w produkcie dzieje się coś ważnego (na przykład ktoś kupuje produkt). Dzięki temu Twój system (CRM, ERP, własna aplikacja, automatyzacja) dostaje dane od razu, bez odpytywania API.
Webhooki konfigurujesz osobno dla każdego produktu i sam decydujesz, jakie zdarzenia mają je wyzwalać oraz jakie dane mają trafić do Twojego systemu.
Gdzie znaleźć webhooki #
Wejdź w Produkty, wybierz produkt, otwórz zakładkę Automatyzacje i przejdź do sekcji Webhooks. Kliknij + Dodaj pierwszą integrację (lub Dodaj webhook, jeśli masz już jakiś skonfigurowany).
Konfiguracja webhooka krok po kroku #
- Adres URL — adres endpointu w Twoim systemie, na który mają trafiać dane.
- Opis — dowolny opis pomocniczy, ułatwia rozróżnienie webhooków na liście.
- Metoda HTTP — GET albo POST (różnice opisane niżej).
- Zdarzenia (triggery) — jedno lub wiele zdarzeń, które wyzwolą webhook (pełna lista niżej).
- Typ autoryzacji — Brak, Basic Auth, Bearer Token albo API Key.
- Payload / parametry — lista pól, które chcesz wysłać, wraz z nazwą klucza pod jaką trafią do Twojego systemu.
- Aktywny — przełącznik włączający webhook.
Lista dostępnych zdarzeń (triggery) #
Nazwa techniczna (pole eventType w payloadzie) zawsze ma prefiks, na przykład product.ProductPurchased.
Dostępne dla każdego produktu (darmowego i płatnego) #
| Zdarzenie (eventType) | Opis | Kiedy się wyzwala |
|---|---|---|
| product.ProductPurchased | Nowa subskrypcja/zakup | Klient kupił produkt (Twój nowy zakup) |
| product.OrderCreated | Utworzono zamówienie | Powstało zamówienie, również przy nieudanej płatności |
| product.ClientImported | Zaimportowano klienta | Klient został dodany przez import |
| productReferrals.ValidSubscriberFromReferral | Zweryfikowane polecenie | Zaliczono ważne polecenie w programie poleceń |
Dodatkowo dla produktu płatnego #
| Zdarzenie (eventType) | Opis |
|---|---|
| product.ProductSubscriptionRenewed | Odnowienie subskrypcji |
| product.ProductSubscriptionEnd | Koniec subskrypcji |
| product.ProductAccessRenewed | Odnowienie okresu dostępu |
| product.ProductAccessPeriodEnd | Koniec okresu dostępu |
| product.ProductAccessPeriodEndingIn14Days | 14 dni do końca okresu dostępu (tylko dla dostępów rocznych) |
| product.ProductAccessPeriodEndingIn7Days | 7 dni do końca okresu dostępu |
| product.ProductAccessPeriodEndingIn3Days | 3 dni do końca okresu dostępu |
| product.ProductAccessPeriodEndingIn1Day | 1 dzień do końca okresu dostępu |
| product.ProductAccessPeriodEndingToday | Okres dostępu kończy się dzisiaj |
| product.ProductClientArchived | Klient zarchiwizowany w produkcie |
Dodatkowo dla produktu darmowego #
| Zdarzenie (eventType) | Opis |
|---|---|
| product.ProductClientRemoved | Klient usunięty z produktu |
[SCREENSHOT: Rozwinięta lista zdarzeń w formularzu webhooka]
Pola payloadu #
Sam wybierasz, które pola wysłać, i pod jaką nazwą klucza mają trafić do Twojego systemu. Dostępne pola:
| Pole | Opis |
|---|---|
| eventType | Typ zdarzenia (pełna nazwa, na przykład product.ProductPurchased) |
| productId | ID produktu |
| productName | Nazwa produktu |
| priceId | ID ceny |
| price | Cena: obiekt z kwotą, walutą i stawką VAT |
| paymentType | Rodzaj płatności |
| orderId | Numer transakcji |
| quantity | Liczba zakupionych (domyślnie 1) |
| clientEmail | Email klienta |
| clientFirstName | Imię klienta |
| clientLastName | Nazwisko klienta |
| clientName | Imię i nazwisko klienta (połączone) |
| clientAddress | Adres klienta |
| phoneNumber | Numer telefonu |
| companyName | Nazwa firmy |
| taxNumber | NIP |
| consents | Dodatkowe zgody |
| discordId | Discord ID |
| additionalInfo | Dodatkowe informacje |
Jak budowany jest payload #
- Dla każdego pola podajesz własną nazwę klucza (tę, której oczekuje Twój system) i przypisujesz do niej pole z listy powyżej. Dzięki temu dopasujesz payload do swojego odbiornika, bez przerabiania go po swojej stronie.
- POST — dane lecą jako JSON w body. Możesz też zaznaczyć opcję wysyłki payloadu jako parametry zapytania.
- GET — dane lecą jako parametry w adresie URL.
- eventType zawsze zawiera pełną nazwę zdarzenia z prefiksem (na przykład product.ProductPurchased).
- price to obiekt zawierający kwotę, walutę i stawkę VAT.
- clientName łączy imię i nazwisko klienta.
Przykładowy payload dla nowego zakupu (POST) #
Przy mapowaniu kluczy 1:1 z nazwami pól payload nowego zakupu wygląda tak:
{
"eventType": "product.ProductPurchased",
"orderId": "ord_xxxxxxxx",
"productId": "prod_xxxxxxxx",
"productName": "Nazwa Twojego produktu",
"priceId": "price_xxxxxxxx",
"price": {
"amount": 9900,
"currency": "PLN",
"taxRate": 23
},
"clientEmail": "jan.kowalski@example.com",
"clientFirstName": "Jan",
"clientLastName": "Kowalski",
"quantity": 1
}UWAGA: dokładny format pola amount (na przykład czy kwota jest w groszach) najlepiej potwierdzić na realnym zdarzeniu testowym za pomocą funkcji testowania webhooka (patrz niżej). Wartości w przykładzie są poglądowe.
Autoryzacja #
Przy konfiguracji wybierasz typ autoryzacji, którego ma używać webhook wysyłany do Twojego systemu:
- Brak — bez autoryzacji.
- Basic Auth — login i hasło.
- Bearer Token — token przekazywany w nagłówku Authorization.
- API Key — klucz przekazywany jako parametr.
Ważne uwagi techniczne #
- Webhook jest wysyłany jednorazowo, bez automatycznych ponowień. Twój endpoint powinien przyjąć żądanie od razu i odpowiedzieć statusem z zakresu 2xx. Jeśli Twój serwer nie odpowie poprawnie, Zanfia nie ponowi próby automatycznie.
- Wynik każdej wysyłki (sukces lub błąd, kod odpowiedzi) zapisuje się w logach webhooka, więc możesz sprawdzić, czy żądanie doszło i jak odpowiedział Twój system.
Testowanie webhooka #
Przed wpięciem na produkcję możesz wysłać testowe żądanie na swój endpoint i sprawdzić, czy dane dochodzą w oczekiwanym formacie.
Dodatkowe materiały #
- Dokumentacja Zanfia API: help.zanfia.com/pl/docs/jak-wykorzystac-api-zanfia
- Wideo o webhookach: youtube.com/watch?v=PBro2WZzbC8
