Webhooki
Webhooki wysyłają zdarzenia dotyczące Twoich klientów z ECDP do Twojego systemu zaraz po tym, jak się wydarzą. Dzięki nim możesz na bieżąco synchronizować zgody z własnym CRM lub ERP albo śledzić dostarczenia, otwarcia i kliknięcia wiadomości, bez cyklicznego odpytywania API.
Zdarzenia, które możesz wysyłać
Każdy webhook wysyła jeden typ zdarzenia. Wybierz kategorię, a potem typ zdarzenia z tej kategorii:
- Zgody – Zgoda udzielona, Zgoda oczekuje na potwierdzenie, Zgoda potwierdzona, Zgoda wycofana.
- E-mail – Wysłanie, Dostarczenie, Odbicie, Skarga, Otwarcie, Kliknięcie.
- SMS – Wysłanie, Odbicie, Kliknięcie.
- Web push – Wysłanie, Wyświetlenie, Kliknięcie.
- Mobile push – Wysłanie, Wyświetlenie, Kliknięcie.
Jeśli jedna operacja zmienia kilka zgód klienta naraz, ECDP wysyła osobne żądanie dla każdej zmienionej zgody. Co zawiera każde żądanie, sprawdzisz w sekcji Payloady webhooków.
Kiedy ECDP wysyła zdarzenia zgód. ECDP wysyła zdarzenie zgody, gdy zgoda klienta zmienia się, bo:
- klient wysyła formularz na stronie albo powstaje na Twojej stronie dzięki skryptowi web tracking. Zgoda single opt-in wysyła Zgodę udzieloną. Zgoda double opt-in wysyła Zgodę oczekującą na potwierdzenie.
- klient klika link potwierdzający w e-mailu double opt-in. ECDP wysyła Zgodę potwierdzoną.
- dodajesz, aktualizujesz lub usuwasz klienta przez API, w panelu ECDP albo w centrum preferencji. ECDP wysyła Zgodę udzieloną, Zgodę oczekującą na potwierdzenie lub Zgodę wycofaną dla każdej zmienionej zgody.
- klient wypisuje się linkiem w e-mailu lub SMS-ie albo z wiadomości web push, albo jego zgody wycofuje skarga na spam. ECDP wysyła Zgodę wycofaną.
- klient subskrybuje web push albo rejestrowane jest urządzenie mobilne. ECDP wysyła Zgodę udzieloną.
ECDP nie wysyła zdarzeń zgód przy imporcie klientów, akcjach masowych w panelu ani akcjach scenariusza ustawiających dane klienta.
Tworzenie webhooka
- Przejdź do Ustawienia > Webhooki.
- Na zakładce Webhooki kliknij Stwórz webhook.
- Wpisz Nazwę.
- Wybierz Kategorię i Typ zdarzenia.
- Jeśli wybierzesz kategorię Zgody, w polu Ogranicz do wybranych zgód możesz wskazać jedną lub kilka zgód. Jeśli zostawisz je puste, webhook uruchamia się dla wszystkich zgód w jednostce biznesowej.
- W polu Adres docelowy wpisz adres, na który mają trafiać zdarzenia. Musi zaczynać się od https://.
- Jeśli Twój system wymaga uwierzytelniania, wypełnij dwa ostatnie pola: nazwę nagłówka uwierzytelniającego i jego wartość. Nazwa jest domyślnie wypełniona jako ApiKey. Możesz ją zmienić, żeby pasowała do Twojego systemu, np. na Authorization albo X-API-KEY. ECDP dołącza ten nagłówek do każdego żądania, także testowego.
- Kliknij Sprawdź połączenie. ECDP wyśle na Twój adres żądanie testowe. Wynik pojawi się obok przycisku.
- Gdy test się powiedzie, kliknij Aktywuj. Webhook zaczyna działać od razu.

Wskazówka: Nie zapiszesz webhooka, dopóki test połączenia się nie powiedzie. Do tego czasu podpowiedź pod przyciskami mówi, co zrobić.
Jak działa test połączenia
- Żądanie testowe zawiera pola wybranego zdarzenia wypełnione przykładowymi danymi, np. ID klienta 123 i adres z example.com. Nigdy nie zawiera danych prawdziwych klientów. Niektóre pola mogą się nieznacznie różnić od prawdziwego żądania, więc jako wzorca używaj sekcji Payloady webhooków.
- Test kończy się sukcesem, gdy Twój system odpowie kodem 2xx lub 4xx, bo adres jest osiągalny. Przy 4xx wynik pokazuje kod i odpowiedź, więc widzisz, że Twój system odrzucił dane testowe.
- Test kończy się niepowodzeniem, gdy Twój system odpowie kodem 3xx lub 5xx, nie odpowie w wyznaczonym czasie albo nie uda się połączyć.
- Test nie jest dostarczeniem. Nie pojawia się w logach i nie zmienia wyniku ani daty ostatniego żądania na liście webhooków.
Zarządzanie webhookami
Zakładka Webhooki pokazuje listę Twoich webhooków: nazwę, status, typ zdarzenia, wynik i datę ostatniego żądania oraz datę ostatniej edycji. Wynik i data pokazują ostatnie zakończone dostarczenie, po wszystkich ponowieniach. Zanim webhook wyśle pierwsze żądanie, w kolumnie wyniku widzisz myślnik.
- Aktywny – webhook dostarcza zdarzenia. Możesz go dezaktywować, edytować albo otworzyć jego logi.
- Nieaktywny – webhook nie dostarcza zdarzeń. Możesz go aktywować, edytować, usunąć albo otworzyć jego logi.
- Usunięty – domyślnie ukryty. Zaznacz Pokaż usunięte webhooki nad tabelą, żeby go zobaczyć. Możesz go przywrócić albo otworzyć jego logi.

Najedź na ikonę w wierszu, żeby zobaczyć jej nazwę, np. Dezaktywuj, Edytuj albo Zobacz logi. Żeby usunąć webhook, kliknij ikonę usuwania i potwierdź w oknie, które się otworzy.
Edycja: webhook możesz edytować w każdym statusie. Żeby zapisać zmiany, sprawdź połączenie ponownie i kliknij Zaktualizuj. Webhook działa bez przerwy w trakcie edycji, a jego status się nie zmienia.
Limit aktywnych webhooków: możesz mieć kilka webhooków dla tego samego zdarzenia, np. żeby wysłać je do kilku systemów. Domyślnie możesz mieć do 4 aktywnych webhooków dla tego samego typu zdarzenia. Jeśli utworzenie lub aktywacja webhooka przekroczyłaby limit, ECDP pokaże komunikat o osiągnięciu limitu i nie zapisze ani nie aktywuje webhooka. Limit obowiązuje też wtedy, gdy zmieniasz typ zdarzenia aktywnego webhooka. Przywrócony webhook jest nieaktywny, więc ECDP sprawdza limit dopiero przy jego aktywacji. Dezaktywuj albo usuń webhook, którego nie potrzebujesz, i spróbuj ponownie.
Jak działa dostarczanie
- ECDP wysyła każde zdarzenie jako żądanie na Twój adres docelowy krótko po tym, jak się wydarzy. Nie gwarantuje natychmiastowego dostarczenia. Przy dużej liczbie zdarzeń, np. podczas dużej kampanii, webhooki mogą docierać z opóźnieniem.
- Jedno zdarzenie tworzy jedno dostarczenie dla każdego aktywnego webhooka skonfigurowanego dla tego zdarzenia, bez duplikatów. Jeśli w jednostce biznesowej nie ma aktywnego webhooka dla danego typu zdarzenia, ECDP niczego nie wysyła.
- Dostarczenie udaje się tylko wtedy, gdy Twój system odpowie kodem 2xx.
- Jeśli Twój system odpowie kodem 3xx, próba kończy się niepowodzeniem, a ECDP nie podąża za przekierowaniem i nie ponawia próby.
- Jeśli Twój system odpowie kodem 4xx innym niż 408 i 429, odrzucił dane. Próba kończy się niepowodzeniem, a ECDP nie ponawia jej.
- Jeśli Twój system odpowie kodem 5xx, 408 lub 429, nie odpowie w wyznaczonym czasie albo nie uda się połączyć, ECDP ponawia próbę od razu, bez przerwy między próbami, do limitu ponowień ustawionego dla Twojej jednostki biznesowej. Limit ponowień liczy powtórzenia po pierwszym żądaniu, więc limit 2 oznacza maksymalnie 3 żądania łącznie.
- Po ostatniej próbie zdarzenie jest oznaczone w logach jako nieudane. ECDP nie ponawia go już później.
- ECDP nigdy sam nie dezaktywuje webhooka, nawet gdy dostarczenia stale się nie udają. Sprawdzaj wynik ostatniego żądania na liście i logi.
- ECDP wysyła żądania tylko na publiczne adresy https://. Nie dotrze do adresów w sieci prywatnej.
- Wszystkie daty w żądaniach są w strefie czasowej Twojej jednostki biznesowej, w formacie ISO 8601 z przesunięciem względem UTC.
Ustawienia webhooków dla jednostki biznesowej
Na zakładce Ustawienia w Ustawienia > Webhooki ustawiasz wartości obowiązujące wszystkie webhooki w jednostce biznesowej:
- Limit czasu odpowiedzi (ms) – jak długo ECDP czeka na odpowiedź na każde żądanie. Jeśli Twój system nie odpowie w tym czasie, próba jest liczona jako nieudana. Możesz wpisać wartość od 100 do 10 000. Domyślnie to 3 000.
- Limit ponowień – ile razy ECDP powtarza nieudane dostarczenie po pierwszym żądaniu. Możesz wpisać wartość od 0 do 5. Przy 0 ECDP nie ponawia. Domyślnie to 2, czyli maksymalnie 3 żądania łącznie.
- Przechowywanie logów (dni) – jak długo przechowywane są wpisy w logu webhooków. Możesz wpisać wartość od 1 do 90. Domyślnie to 30.
Gdy skończysz, kliknij Zapisz.
Sprawdzanie dostarczeń w logach
Przejdź do Ustawienia > Logi i otwórz zakładkę Webhooki. Możesz też kliknąć Zobacz logi w wierszu webhooka. ECDP otworzy tę zakładkę z kolumną Webhook już przefiltrowaną do tego webhooka.
Tabela pokazuje Wynik (Udane albo Nieudane), ID, Webhook, datę i godzinę utworzenia wpisu (Utworzono) i Liczbę prób. Jedno dostarczenie to jeden wpis, niezależnie od tego, ile razy ECDP musiał je ponawiać. Liczba prób pokazuje, ile żądań było potrzebnych, a wpis pokazuje wynik ostatniej próby. Zdarzenie dostarczone za trzecim razem to jeden wpis z 3 próbami. W logach są tylko dostarczenia zdarzeń, bez testów połączenia. Najnowsze wpisy są na górze, a filtrować możesz po każdej kolumnie.
Kliknij ikonę oka na końcu wiersza, żeby otworzyć panel Szczegóły logu webhooka:
- Szczegóły – webhook, data utworzenia, adres docelowy, metoda, status odpowiedzi, wynik, liczba prób, komunikat błędu, token i czas przetwarzania. Komunikat błędu to odpowiedź Twojego systemu albo krótki opis problemu. Token jest zawsze zamaskowany albo pusty, jeśli webhook nie ma nagłówka uwierzytelniającego.
- Treść żądania – treść żądania w formacie JSON, sformatowana dla czytelności. Kliknij ikonę kopiowania w polu, żeby go skopiować.

Wskazówka: Wpisy starsze niż ustawiony okres przechowywania znikają z logu i z wyników wyszukiwania. Jeśli diagnozujesz powtarzające się błędy, przejrzyj je, zanim wygasną.
Payloady webhooków
Ta sekcja opisuje żądania, które ECDP wysyła na Twój adres docelowy po uruchomieniu webhooka.
Format żądania
- ECDP wysyła każde zdarzenie jako żądanie POST. Treść to jeden obiekt JSON (UTF-8), a nagłówek Content-Type ma wartość application/json.
- Jeśli w webhooku ustawisz nagłówek uwierzytelniający, ECDP dołącza go do każdego żądania pod wpisaną przez Ciebie nazwą i z wpisaną wartością.
- Każde zdarzenie tworzy osobne żądanie. Na przykład, jeśli jedno wywołanie API zmienia trzy zgody klienta, dostajesz trzy żądania.
- Żądanie testowe zawiera przykładowe dane i może się nieznacznie różnić od prawdziwego żądania. Jako wzorca używaj tej sekcji.
- W tekście JSON znaki takie jak + i & mogą być zapisane jako \u002B i \u0026. Każdy parser JSON odczyta je poprawnie, więc nie trzeba ich osobno obsługiwać.
- Nazwy pól są zapisane w camelCase. eventType to nazwa zdarzenia, np. Send. Ta sama nazwa występuje w kilku kanałach, np. Send i Click, więc kanał rozpoznasz po pozostałych polach.
- ECDP pomija pola, które nie mają wartości. Nie wysyła ich z wartością null. Pomija też puste pola crmId, email, phone, channel i version.
- Żądanie nie zawiera Twojego klucza API, adresu docelowego ani nazwy webhooka.
Pola w każdym zdarzeniu
| Pole | Typ | Opis |
| eventId | string (UUID) | Unikalne ID zdarzenia. Jeśli ECDP ponowi dostarczenie, ponowione żądanie ma to samo eventId, więc po Twojej stronie możesz je wykorzystać do wykrywania duplikatów. Jeśli kilka webhooków reaguje na to samo zdarzenie, każdy z nich dostaje to samo eventId. |
| eventType | string | Typ zdarzenia, np. ConsentGiven, Send albo Click. |
| category | string | Kategoria zdarzenia: Consents, Email, Sms, WebPush albo MobilePush. |
| eventDate | string (ISO 8601) | Kiedy ECDP opublikował zdarzenie. To nie jest czas pierwotnej wysyłki, kliknięcia ani wywołania zwrotnego. Data jest w strefie czasowej Twojej jednostki biznesowej, z pełnymi sekundami i przesunięciem względem UTC, np. 2026-08-26T12:05:33+02:00. |
| customerId | number | ID klienta w ECDP. |
| crmId | string | CRM ID klienta. Wysyłane tylko wtedy, gdy jest dostępne. |
| string | Aktualny adres e-mail klienta. Wysyłany tylko wtedy, gdy jest dostępny. | |
| phone | string | Aktualny numer telefonu klienta w formacie międzynarodowym, z prefiksem kraju i bez spacji. Wysyłany tylko wtedy, gdy jest dostępny. |
ECDP bierze dane kontaktowe z danych klienta w chwili budowania żądania. Nie muszą to być ten sam adres e-mail ani numer telefonu, które zostały użyte przy pierwotnej wysyłce. Identyfikatory klienta nie są ograniczone do kanału zdarzenia: zdarzenie SMS może zawierać także email.
Zdarzenia zgód
Typy zdarzeń: ConsentGiven, ConsentAwaitingConfirmation, ConsentConfirmed, ConsentRevoked. Oprócz wspólnych pól te zdarzenia zawierają:
| Pole | Typ | Opis |
| consentId | number | ID zgody. |
| consentName | string | Nazwa zgody. |
| channel | string | Kanał zgody: Email, Sms, WebPush albo MobileApplication. Dla zgody ogólnej ECDP go pomija. |
Przykład: ConsentGiven
{
"eventId": "11111111-1111-4111-8111-000000000001",
"eventType": "ConsentGiven",
"category": "Consents",
"eventDate": "2026-08-26T12:05:33+02:00",
"customerId": 12345,
"crmId": "CRM-DEMO-12345",
"email": "customer@example.com",
"consentId": 10,
"consentName": "Email communication consent",
"channel": "Email"
}Przykład: ConsentRevoked dla zgody ogólnej. Nie ma pola channel.
{
"eventId": "11111111-1111-4111-8111-000000000004",
"eventType": "ConsentRevoked",
"category": "Consents",
"eventDate": "2026-08-26T12:08:33+02:00",
"customerId": 12345,
"crmId": "CRM-DEMO-12345",
"consentId": 11,
"consentName": "General consent"
}Gdy klient potwierdza zgodę double opt-in, dostajesz tylko zdarzenie ConsentConfirmed, bez dodatkowego ConsentGiven.
Zdarzenia e-mail
Typy zdarzeń: Send, Delivery, Bounce, Complaint, Open, Click. Send oznacza, że e-mail został wysłany, a nie że dotarł do odbiorcy. Oprócz wspólnych pól te zdarzenia zawierają:
| Pole | Zdarzenia | Opis |
| messageId | Wszystkie | ID wiadomości (number). |
| messageType | Wszystkie | Typ wiadomości: Newsletter, Scenario albo Confirmation. |
| messageSubjectOrName | Wszystkie | Temat wiadomości. Jeśli wiadomość nie ma tematu, to pusty ciąg znaków. |
| version | Wszystkie | Wariant, który klient dostał w teście A/B: A, B, C itd. albo Winner dla kopii zwycięskiej wersji. Wysyłane tylko dla wiadomości z testem A/B. |
| bounceReason | Bounce | Powód odbicia: UserUnknown, MailboxFull, Blocked, Unknown albo Other. |
| bounceType | Bounce | Typ odbicia: Hard, Soft, Transparent, Block albo Other. |
| targetUrl | Click | Docelowy adres linku, w który kliknął klient, a nie adres przekierowania śledzącego. Zawiera wszystkie parametry, także te, które ECDP dodaje do linku, np. UTM. |
Przykład: Send
{
"eventId": "11111111-1111-4111-8111-000000000005",
"eventType": "Send",
"category": "Email",
"eventDate": "2026-08-26T12:09:33+02:00",
"customerId": 12345,
"email": "customer@example.com",
"messageId": 2001,
"messageType": "Newsletter",
"messageSubjectOrName": "Sample message",
"version": "A"
}Przykład: Bounce
{
"eventId": "11111111-1111-4111-8111-000000000007",
"eventType": "Bounce",
"category": "Email",
"eventDate": "2026-08-26T12:11:33+02:00",
"customerId": 12345,
"email": "customer@example.com",
"messageId": 2001,
"messageType": "Newsletter",
"messageSubjectOrName": "Sample message",
"bounceReason": "UserUnknown",
"bounceType": "Hard"
}Przykład: Click
{
"eventId": "11111111-1111-4111-8111-000000000010",
"eventType": "Click",
"category": "Email",
"eventDate": "2026-08-26T12:14:33+02:00",
"customerId": 12345,
"email": "customer@example.com",
"messageId": 2001,
"messageType": "Newsletter",
"messageSubjectOrName": "Sample message",
"targetUrl": "https://shop.example.com/products/demo"
}Zdarzenia Delivery, Complaint i Open mają te same pola co Send. Complaint nie ma pola opisującego skargę.
Zdarzenia SMS
Typy zdarzeń: Send, Bounce, Click. Send oznacza, że SMS został wysłany, a nie że dotarł na telefon. Oprócz wspólnych pól te zdarzenia zawierają:
| Pole | Zdarzenia | Opis |
| messageId | Wszystkie | ID wiadomości (number). |
| messageType | Wszystkie | Typ wiadomości: Newsletter albo Scenario. |
| failureReason | Bounce | Status zgłoszony przez bramkę SMS, gdy wiadomość nie została dostarczona, np. kod statusu z jego nazwą. ECDP przekazuje go bez zmian, więc nie jest to zamknięta lista wartości i zależy od bramki. |
| targetUrl | Click | Docelowy adres linku, w który kliknął klient. Zawiera wszystkie parametry, także te, które ECDP dodaje do linku, np. UTM. |
Przykład: Bounce
{
"eventId": "11111111-1111-4111-8111-000000000012",
"eventType": "Bounce",
"category": "Sms",
"eventDate": "2026-08-26T12:16:33+02:00",
"customerId": 12345,
"phone": "+12025550123",
"messageId": 3001,
"messageType": "Newsletter",
"failureReason": "DEMO_UNDELIVERABLE"
}Zdarzenia web push
Typy zdarzeń: Send, View, Click. Send oznacza, że powiadomienie zostało przekazane do dostawcy push, a nie że zostało wyświetlone. Oprócz wspólnych pól te zdarzenia zawierają:
| Pole | Zdarzenia | Opis |
| messageId | Wszystkie | ID powiadomienia (number). |
| messageType | Wszystkie | Typ powiadomienia: Newsletter albo Scenario. |
| websiteId | Wszystkie | ID strony (number). |
| targetUrl | Click | Docelowy adres linku, w który kliknął klient. Zawiera wszystkie parametry, także te, które ECDP dodaje do linku, np. UTM. |
Przykład: Click
{
"eventId": "11111111-1111-4111-8111-000000000016",
"eventType": "Click",
"category": "WebPush",
"eventDate": "2026-08-26T12:20:33+02:00",
"customerId": 12345,
"messageId": 4001,
"messageType": "Newsletter",
"websiteId": 100,
"targetUrl": "https://shop.example.com/news/demo"
}Zdarzenia mobile push
Typy zdarzeń: Send, View, Click. Send oznacza, że powiadomienie zostało przekazane do dostawcy push, a nie że zostało wyświetlone. Oprócz wspólnych pól te zdarzenia zawierają:
| Pole | Opis |
| messageId | ID powiadomienia (number). |
| messageType | Typ powiadomienia: Newsletter albo Scenario. |
| mobileApplicationId | ID aplikacji mobilnej (number). |
| deviceId | Publiczne ID urządzenia klienta (string). |
Przykład: Send
{
"eventId": "11111111-1111-4111-8111-000000000017",
"eventType": "Send",
"category": "MobilePush",
"eventDate": "2026-08-26T12:21:33+02:00",
"customerId": 12345,
"crmId": "CRM-DEMO-12345",
"messageId": 5001,
"messageType": "Scenario",
"mobileApplicationId": 200,
"deviceId": "demo-device-001"
}Zdarzenia View i Click mają te same pola. Zdarzenia mobile push nie zawierają linku.
Czy webhooki wysyłają zmiany zgód z importu?
Nie. Zmiany zgód wprowadzone przez import danych klientów nie uruchamiają webhooków. Dotyczy to też akcji masowych i akcji scenariusza ustawiających dane klienta. Operacje, które wysyłają zdarzenia zgód, znajdziesz w sekcji Zdarzenia, które możesz wysyłać.