Skonfiguruj webhooki

Opublikowano: 16 lipca 2026 · Ostatnia aktualizacja: 12 września 2026 · Autor: Marcus Biel

Webhooki pozwalają Maildroppa powiadamiać inną aplikację, gdy na koncie wystąpi ważne zdarzenie.

Zamiast wielokrotnie sprawdzać w Maildroppa, czy utworzono subskrybenta, zaktualizowano jego dane, wypisano go lub przypisano mu tag, aplikacja może otrzymać żądanie HTTPS krótko po wystąpieniu zdarzenia.

Strona „Webhooks” to centralne miejsce zarządzania tą integracją dla całego konta. Możesz utworzyć kilka endpointów, wybrać zdarzenia otrzymywane przez każdy z nich, dodać nagłówki uwierzytelniające, przetestować połączenie, sprawdzić próby dostarczenia i w razie potrzeby ponownie wysłać zdarzenie produkcyjne.

Jak działają webhooki konta

Webhook konta działa następująco:

1. W Maildroppa występuje zdarzenie, na przykład utworzenie subskrybenta.
2. Maildroppa wyszukuje wszystkie aktywne endpointy subskrybujące to zdarzenie.
3. Maildroppa tworzy po jednym dostarczeniu dla każdego pasującego endpointu.
4. Ładunek JSON jest podpisywany sekretem do podpisywania webhooków konta — „Signing secret”.
5. Maildroppa wysyła żądanie HTTPS POST na zapisany adres URL endpointu.
6. Endpoint weryfikuje podpis, zapisuje lub przetwarza zdarzenie i zwraca odpowiedź HTTP.
7. Maildroppa zapisuje wynik w historii dostarczeń i automatycznie ponawia próby w przypadku błędów tymczasowych.

Jeśli kilka endpointów subskrybuje to samo zdarzenie, każdy otrzymuje osobne dostarczenie. Zdarzenie biznesowe ma ten sam identyfikator Event ID dla wszystkich endpointów, natomiast każde dostarczenie ma własny identyfikator Delivery ID.

Webhooki konta różnią się od kroku „Send a webhook” w automatyzacji. Webhooki konta nasłuchują wybranych zdarzeń konta w całym Maildroppa. Webhook automatyzacji jest wysyłany tylko wtedy, gdy subskrybent dotrze do tego konkretnego kroku. Oba mechanizmy korzystają z tego samego sekretu do podpisywania webhooków konta, więc jego rotacja wpływa na wszystkie odbiorniki wychodzących webhooków, które weryfikują podpisy Maildroppa.

Otwórz stronę Webhooks

Otwórz „Settings”, rozwiń „Developers” i wybierz „Webhooks”.

Strona zawiera trzy główne obszary:

• Signing secret — sekret do podpisywania
• Endpoints — endpointy
• Delivery history — historia dostarczeń dla wybranego endpointu

Jeśli masz więcej niż jeden endpoint, wybierz jego wiersz, aby wyświetlić historię dostarczeń. Jeśli nie wybierzesz żadnego endpointu, Maildroppa pokaże historię pierwszego na liście.

Zanim utworzysz endpoint

Przed skonfigurowaniem Maildroppa przygotuj odbiornik na swoim serwerze. Powinien on:

• Być dostępny pod publicznym adresem HTTPS.
• Akceptować żądania POST z treścią typu application/json.
• Zachowywać surową treść żądania do czasu zweryfikowania podpisu Maildroppa.
• Zwracać status 2xx dopiero po bezpiecznym przyjęciu zdarzenia.
• Przetwarzać powtarzające się dostarczenia idempotentnie, korzystając z Event ID.
• Odpowiadać szybko, zamiast wykonywać czasochłonne operacje w trakcie obsługi żądania.

Sprawdzony schemat to weryfikacja żądania, zapisanie Event ID i ładunku w trwałej kolejce lub bazie danych, zwrócenie 200 albo 204, a dopiero potem wykonanie operacji biznesowej.

Nie udostępniaj komputera deweloperskiego, lokalnego adresu sieciowego ani niezabezpieczonego skryptu jako produkcyjnego odbiornika webhooków. Maildroppa akceptuje wyłącznie publiczne adresy docelowe HTTPS i ponownie sprawdza cel przy wysyłaniu dostarczenia.

Krok 1: wygeneruj sekret do podpisywania

Każde żądanie webhooka Maildroppa jest podpisane. Odbiornik używa sekretu „Signing secret”, aby zweryfikować, czy żądanie pochodzi z Maildroppa i czy jego treść nie została zmieniona podczas przesyłania.

Panel „Signing secret” u góry strony pokazuje jeden z następujących stanów:

• Missing — sekret do podpisywania jeszcze nie istnieje.
• Ready — sekret do podpisywania jest skonfigurowany.
• Loading — Maildroppa pobiera bieżący stan.

Jeśli widzisz stan „Missing”, kliknij „Generate secret”.

Maildroppa od razu wyświetli nowy sekret. Jego wartość zaczyna się od whsec_. Kliknij „Copy” i zapisz go w menedżerze sekretów lub chronionej konfiguracji środowiska, z której korzysta odbiornik.

Pełna wartość jest widoczna tylko bezpośrednio po wygenerowaniu lub rotacji. Po ponownym załadowaniu strony lub jej opuszczeniu Maildroppa pokazuje jedynie, że sekret istnieje, oraz datę jego ostatniej aktualizacji. Zapisany sekret nie jest ponownie ujawniany.

Jeśli utracisz sekret

Jeśli odbiornik nie ma już bieżącego sekretu, kliknij „Rotate secret” i zapisz nowo wyświetloną wartość.

Rotacja natychmiast zastępuje poprzedni sekret. Maildroppa nie zachowuje obu wartości na okres przejściowy. Zaktualizuj każdy odbiornik korzystający z tego sekretu konta, zanim wyślesz kolejne testy lub zaczniesz polegać na dostarczeniach produkcyjnych.

Nowe dostarczenia, zaplanowane ponowienia, testy i ręczne ponowne wysyłki są podpisywane sekretem aktualnym w chwili wysyłania żądania HTTP. Oznacza to, że dostarczenie utworzone przed rotacją może zostać podpisane nowym sekretem, jeśli próba wysłania nastąpi po rotacji.

Traktuj sekret jak hasło

Nie umieszczaj sekretu do podpisywania w kodzie wykonywanym w przeglądarce, publicznym repozytorium, adresie URL, na stronie błędu ani w zwykłym logu aplikacji.

Sekret jest potrzebny wyłącznie odbiornikowi działającemu po stronie serwera. Jeśli podejrzewasz jego ujawnienie, natychmiast przeprowadź rotację i zaktualizuj wszystkie odbiorniki.

Zweryfikuj podpis webhooka

Każde żądanie zawiera następujące nagłówki Maildroppa:

• X-Maildroppa-Event-Id — identyfikuje zdarzenie biznesowe.
• X-Maildroppa-Delivery-Id — identyfikuje konkretne dostarczenie.
• X-Maildroppa-Timestamp — czas podpisania jako uniksowy znacznik czasu w sekundach.
• X-Maildroppa-Signature — podpis HMAC z oznaczeniem wersji.

Maildroppa wysyła również:

• Content-Type: application/json
• User-Agent: Maildroppa-Webhooks/1.0

Podpis ma następujący format:

v1=<lowercase hexadecimal HMAC>

Maildroppa tworzy go za pomocą HMAC-SHA256. Podpisywana treść składa się ze znacznika czasu, kropki i dokładnej, surowej treści żądania JSON:

<timestamp>.<raw request body>

Jako klucza HMAC użyj sekretu do podpisywania.

Poniższy przykład w Node.js pokazuje podstawowy etap weryfikacji. rawBody musi zawierać oryginalne bajty żądania, a nie JSON, który został już sparsowany i ponownie zserializowany.

import crypto from 'node:crypto';

export function verifyMaildroppaWebhook({ rawBody, timestamp, signature, signingSecret }) {
  const signedPayload = Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), rawBody]);

  const expectedSignature = `v1=${crypto
    .createHmac('sha256', signingSecret)
    .update(signedPayload)
    .digest('hex')}`;

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(expectedSignature, 'utf8');

  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

Po zweryfikowaniu podpisu porównaj także znacznik czasu z czasem serwera. Odrzucaj żądania wykraczające poza krótki przedział tolerancji przyjęty dla danej infrastruktury, na przykład pięć minut. Zmniejsza to ryzyko ponownego przesłania przechwyconego, prawidłowego żądania znacznie później.

Parsuj i przetwarzaj JSON dopiero po pomyślnym zakończeniu obu kontroli.

Najczęstsze przyczyny błędów podpisu

Weryfikacja podpisu zwykle nie udaje się z jednego z następujących powodów:

• Odbiornik używa starego sekretu po rotacji.
• Middleware sparsował lub zmienił JSON przed obliczeniem podpisu.
• Odbiornik podpisuje tylko treść żądania i pomija <timestamp>..
• Znacznik czasu jest traktowany jako sformatowana data zamiast dokładnej wartości nagłówka.
• W porównaniu pominięto prefiks v1=.
• Obliczony HMAC jest zakodowany inaczej niż w zapisie szesnastkowym z małymi literami.

Gdy weryfikacja się nie powiedzie, zapisuj w logach Event ID i Delivery ID, ale nigdy nie zapisuj sekretu do podpisywania ani poufnych wartości niestandardowych nagłówków.

Krok 2: dodaj endpoint

Kliknij „Add endpoint” w sekcji „Endpoints”.

Edytor składa się z czterech części:

• Endpoint URL — adres URL endpointu
• Events — zdarzenia
• Custom headers — niestandardowe nagłówki
• Active — status aktywności

Nowe endpointy są domyślnie aktywne, a wszystkie zdarzenia widoczne w edytorze są początkowo zaznaczone. Sprawdź wybór przed zapisaniem, aby odbiornik otrzymywał tylko potrzebne powiadomienia.

Skonfiguruj adres URL endpointu

Wprowadź pełny publiczny adres URL, pod który mają trafiać żądania Maildroppa, na przykład:

https://integrations.example.com/webhooks/maildroppa

Adres URL musi spełniać następujące wymagania:

• Musi używać https://.
• Musi zawierać prawidłową publiczną nazwę hosta.
• Może mieć maksymalnie 2 048 znaków.
• Nie może zawierać zmiennych szablonu z { lub }.
• Nie może zawierać nazwy użytkownika ani hasła przed nazwą hosta.
• Nie może zawierać fragmentu URL rozpoczynającego się od #.
• Musi używać standardowego portu HTTPS 443.
• Nie może używać localhost, bezpośredniego adresu IP ani nazwy hosta wskazującej na zablokowaną sieć prywatną lub zarezerwowaną.

Parametry zapytania są obsługiwane, ale nie umieszczaj kluczy API ani innych sekretów w adresie URL. Adresy URL są widoczne na liście endpointów i w danych dostarczeń. Dane uwierzytelniające umieść zamiast tego w niestandardowym nagłówku.

Maildroppa nie podąża za przekierowaniami. Zapisz końcowy adres docelowy HTTPS zamiast adresu URL zwracającego 301, 302, 307 lub 308.

Przed wysłaniem Maildroppa ponownie ustala adres IP docelowej nazwy hosta. Jeśli nazwa zacznie wskazywać na adres prywatny lub zablokowany, zostanie odrzucona — nawet jeśli była prawidłowa w chwili zapisywania endpointu.

Wybierz zdarzenia

Wybierz co najmniej jedno zdarzenie. Endpoint otrzymuje tylko typy zdarzeń zaznaczone w jego edytorze.

Na stronie dostępne są następujące zdarzenia:

Subscriber Created — subscriber.created

Wysyłane po utworzeniu subskrybenta na koncie Maildroppa.

Użyj tego zdarzenia, aby utworzyć odpowiadający mu kontakt w CRM, platformie danych klientów, wewnętrznej bazie danych lub innym systemie uwzględniającym uprawnienia.

Nie traktuj tego zdarzenia jako dowodu, że każdy zapis zakończył się potwierdzeniem subskrypcji przez e-mail w procesie double opt-in. Status subskrybenta w ładunku opisuje jego bieżący stan.

Subscriber Updated — subscriber.updated

Wysyłane po zmianie danych subskrybenta w polach standardowych lub wartości pól niestandardowych.

Traktuj pełny obiekt subskrybenta w ładunku jako jego aktualną reprezentację w Maildroppa. Nie zakładaj, że zmieniła się tylko jedna konkretna właściwość.

Przypisanie i usunięcie tagu mają własne typy zdarzeń, dzięki czemu można je obsługiwać oddzielnie.

Subscriber Unsubscribed — subscriber.unsubscribed

Wysyłane, gdy w wyniku rezygnacji z subskrypcji subskrybent przechodzi do stanu „unsubscribed”.

Użyj tego zdarzenia, aby wykluczyć kontakt z wysyłek w połączonych systemach. Nie zapisuj tej osoby automatycznie ponownie tylko dlatego, że inny system nadal oznacza kontakt jako aktywny.

Tag Added — subscriber.tag_added

Wysyłane po przypisaniu tagu subskrybentowi.

Ładunek zawiera dane subskrybenta i tag, którego dotyczy ta konkretna zmiana.

Tag Removed — subscriber.tag_removed

Wysyłane po usunięciu tagu przypisanego do subskrybenta.

Ładunek zawiera zaktualizowane dane subskrybenta i usunięty tag. Usunięty tag jest przekazywany osobno, mimo że nie znajduje się już w bieżącej tablicy tags subskrybenta.

Form Submitted — form.submitted

Wysyłane, gdy odwiedzający prześle formularz zapisu Maildroppa.

Traktuj to jako informację o przesłaniu formularza, a nie potwierdzenie ukończenia procesu double opt-in. Każdy proces wymagający potwierdzonej subskrypcji musi nadal uwzględniać bieżący status subskrybenta i proces potwierdzenia.

Używaj osobnych endpointów do różnych zadań

Możesz wysyłać różne zdarzenia do różnych systemów. Na przykład:

• Wysyłaj zdarzenia dotyczące subskrybentów i tagów do CRM.
• Wysyłaj zdarzenia rezygnacji z subskrypcji do usługi zarządzającej wykluczeniami z wysyłek.
• Wysyłaj zdarzenia przesłania formularza do potoku analitycznego.

Osobne endpointy ograniczają niepotrzebny ruch i ułatwiają diagnozowanie błędów. Każdy endpoint ma własny zestaw zdarzeń, adres URL, niestandardowe nagłówki, status aktywności, testy i historię dostarczeń.

Dodaj niestandardowe nagłówki

Niestandardowe nagłówki są opcjonalne. Używaj ich, gdy odbiornik wymaga klucza API, tokenu bearer, identyfikatora dzierżawcy lub innego stałego nagłówka.

Kliknij „Add header”, a następnie wprowadź nazwę w polu „Header name” i wartość w polu „Header value”. Przykłady poprawnych nagłówków:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Możesz dodać maksymalnie 20 niestandardowych nagłówków.

Nazwy nagłówków:

• Są wymagane.
• Mogą zawierać maksymalnie 128 znaków.
• Muszą składać się ze znaków dozwolonych w nazwach nagłówków HTTP.
• Muszą być unikalne bez rozróżniania wielkich i małych liter.

Wartości nagłówków:

• Są wymagane.
• Mogą zawierać maksymalnie 2 000 znaków.
• Nie mogą zawierać znaków nowego wiersza.

Następujące nazwy są zarezerwowane i nie można ich użyć do zastąpienia nagłówka nagłówkiem niestandardowym:

• Content-Type
• Content-Length
• Host
• User-Agent
• Każda nazwa rozpoczynająca się od X-Maildroppa-

Zapobiega to zastąpieniu nagłówków dostarczenia i podpisu Maildroppa niestandardowymi wartościami.

Jak przechowywane są sekrety w nagłówkach

Maildroppa szyfruje wartości niestandardowych nagłówków przed ich zapisaniem. Zapisane wartości nie są przesyłane z powrotem do przeglądarki w czytelnej postaci.

Podczas późniejszej edycji endpointu pole wartości pokazuje „Stored value kept”. Pozostaw je puste, jeśli istniejący sekret ma pozostać bez zmian. Wprowadź nową wartość, aby go zastąpić.

Jeśli zmienisz nazwę nagłówka, wprowadź wartość ponownie. Maildroppa zachowuje zapisany sekret tylko wtedy, gdy pierwotna nazwa nagłówka pozostaje bez zmian.

Po usunięciu wiersza nagłówka i zapisaniu endpointu nagłówek nie będzie już dodawany do przyszłych dostarczeń.

W zapisanych informacjach o żądaniach wartości niestandardowych nagłówków są traktowane jako poufne. W historii dostarczeń są maskowane, a nie wyświetlane wprost.

Ustaw endpoint jako aktywny lub nieaktywny

Pozostaw zaznaczoną opcję „Active”, jeśli endpoint jest gotowy do natychmiastowego odbierania zdarzeń.

Odznacz ją, jeśli chcesz zapisać konfigurację bez rozpoczynania dostarczeń. Endpoint możesz aktywować później z poziomu listy endpointów.

Nieaktywny endpoint:

• Nie otrzymuje nowych zdarzeń.
• Nie pozwala na wysłanie testowego webhooka.
• Pozostaje widoczny i można go edytować.
• Zachowuje dostęp do dotychczasowej historii dostarczeń.

Aktywacja endpointu nie powoduje wysłania zaległych zdarzeń, które wystąpiły, gdy był nieaktywny.

Kliknij „Save”, gdy adres URL, wybór zdarzeń, nagłówki i status są prawidłowe.

Lista endpointów

Każdy wiersz endpointu pokazuje:

• Docelowy adres URL.
• Oznaczenie „Active” lub „Inactive”.
• Subskrybowane typy zdarzeń.
• Liczbę niestandardowych nagłówków.
• Czas ostatniej aktualizacji endpointu.

Dostępne działania:

• On/Off — aktywuje lub dezaktywuje endpoint.
• Test — natychmiast wysyła jedno żądanie testowe do aktywnego endpointu.
• Edit — pozwala zmienić adres URL, zdarzenia, nagłówki lub status aktywności.
• Delete — po potwierdzeniu trwale usuwa konfigurację endpointu.

Wybierz główną część wiersza, aby otworzyć historię dostarczeń tego endpointu poniżej listy.

Jak zapisane zmiany wpływają na istniejące dostarczenia

Zdarzenie konta powoduje utworzenie dostarczenia z migawką adresu URL endpointu, ładunku i niestandardowych nagłówków z danego momentu.

Edycja adresu URL lub niestandardowych nagłówków wpływa na nowo tworzone dostarczenia. Dostarczenie, które już trafiło do kolejki, zachowuje pierwotny adres docelowy i zapisaną konfigurację nagłówków.

Zmiana wybranych zdarzeń również wpływa tylko na zdarzenia występujące później. Maildroppa nie tworzy wstecznie dostarczeń dla typów zdarzeń, które nie były wybrane w chwili ich wystąpienia.

Sekret do podpisywania działa inaczej: jest odczytywany podczas przygotowywania żądania HTTP. Oczekujące dostarczenie lub ponowna wysyłka mogą więc użyć nowego sekretu po rotacji, nawet jeśli ładunek i migawka konfiguracji endpointu powstały wcześniej.

Przetestuj endpoint

Gdy odbiornik i sekret do podpisywania są gotowe, kliknij „Test” przy aktywnym endpoincie.

Maildroppa natychmiast wysyła jedno podpisane żądanie, używając zapisanego adresu URL endpointu i zapisanych niestandardowych nagłówków. Niezapisane zmiany w otwartym edytorze nie są uwzględniane w teście.

Ładunek testowy używa typu zdarzenia webhook.test i ustawia livemode na false:

{
  "id": "evt_test_example",
  "type": "webhook.test",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": false,
  "data": {
    "message": "This is a test webhook from Maildroppa."
  }
}

Wygenerowane identyfikatory i znacznik czasu są inne przy każdym rzeczywistym teście.

Test obejmuje dokładnie jedną próbę HTTP. Dostarczenia testowe nie trafiają do produkcyjnego harmonogramu ponowień i nie można ich wysłać ponownie.

Po zakończeniu żądania panel wyników pokazuje:

• Test success lub Test failed — wynik testu
• Event ID
• Status HTTP, jeśli otrzymano odpowiedź
• Czas trwania
• Delivery ID
• Informacje o błędzie, jeśli są dostępne
• Fragment odpowiedzi, jeśli odbiornik zwrócił treść

Test pojawia się również w historii dostarczeń z oznaczeniem „Test”. Użyj filtra „Test”, aby wyświetlić tylko żądania testowe.

Struktura ładunku produkcyjnego

Produkcyjne zdarzenia konta używają wspólnej struktury nadrzędnej JSON:

{
  "id": "evt_example",
  "type": "subscriber.created",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {}
}

Właściwości najwyższego poziomu mają następujące znaczenie:

• id — Event ID. Odpowiada wartości X-Maildroppa-Event-Id.
• type — klucz zdarzenia wybranego w edytorze endpointu.
• schema_version — wersja schematu ładunku. Uwzględniaj ją przy wyborze sposobu parsowania zdarzenia.
• created_at — czas utworzenia ładunku zdarzenia w UTC.
• livemode — true dla zdarzeń produkcyjnych i false dla testowych.
• data — treść właściwa dla danego zdarzenia.

Kieruj zdarzenia do odpowiedniej obsługi na podstawie dokładnej wartości type. Ignoruj dodatkowe właściwości, których integracja nie potrzebuje, aby zgodne wstecznie rozszerzenia ładunku nie zakłócały działania odbiornika.

Ładunek zdarzenia subskrybenta

Zdarzenia subskrybenta zawierają jego bieżącą reprezentację wewnątrz data.subscriber:

{
  "id": "evt_example",
  "type": "subscriber.updated",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [
        {
          "id": "b6594e58-0c4b-4138-9ad8-fc4747e076eb",
          "personalization_tag_name": "company",
          "value": "Example Ltd."
        }
      ],
      "tags": [
        {
          "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
          "name": "Customers"
        }
      ]
    }
  }
}

fields i tags są tablicami i mogą być puste. Właściwość subskrybenta może też mieć wartość null, jeśli nie przypisano jej żadnej wartości. Odbiornik powinien więc działać zgodnie ze schematem ładunku, zamiast zakładać, że wszystkie opcjonalne dane profilu są dostępne.

Ładunek zdarzenia tagu

Zdarzenia tagów zawierają zarówno dane subskrybenta, jak i tag, który wywołał zdarzenie:

{
  "id": "evt_example",
  "type": "subscriber.tag_added",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [],
      "tags": []
    },
    "tag": {
      "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
      "name": "Customers"
    }
  }
}

W przypadku subscriber.tag_removed właściwość data.tag nadal identyfikuje usunięty tag, mimo że bieżąca tablica tags subskrybenta już go nie zawiera.

Event ID, Delivery ID i idempotencja

Event ID i Delivery ID służą różnym celom.

Event ID

Event ID identyfikuje zdarzenie biznesowe. Występuje w:

• Właściwości id na najwyższym poziomie ładunku.
• Nagłówku żądania X-Maildroppa-Event-Id.
• Historii dostarczeń.

To samo zdarzenie może zostać wysłane do kilku subskrybujących je endpointów. Te dostarczenia mają wspólny Event ID.

Automatyczne ponowienia prób i ręczne ponowne wysyłki również zachowują pierwotny Event ID. Przechowuj identyfikatory Event ID przetworzonych zdarzeń i zadbaj o idempotencję operacji biznesowej. Dzięki temu powtórne żądanie nie utworzy zduplikowanych kontaktów, nie powtórzy nieodwracalnej operacji ani nie zastosuje tej samej zmiany dwukrotnie.

Delivery ID

Delivery ID identyfikuje pojedynczy rekord dostarczenia. Występuje w:

• Nagłówku żądania X-Maildroppa-Delivery-Id.
• Historii dostarczeń.

Każde dostarczenie do endpointu ma własny Delivery ID. Ręczna ponowna wysyłka tworzy nowy Delivery ID, zachowując pierwotny Event ID.

Używaj Delivery ID do śledzenia technicznego i kontaktu z pomocą techniczną, a Event ID — do deduplikacji na poziomie operacji biznesowych.

Zwracaj prawidłową odpowiedź HTTP

Maildroppa klasyfikuje odpowiedzi następująco:

• Każda odpowiedź 2xx oznacza pomyślne dostarczenie.
• Odpowiedzi 408 Request Timeout, 429 Too Many Requests i 5xx oznaczają błędy tymczasowe, po których można ponowić próbę.
• Błędy sieciowe, które mogą być tymczasowe, powodują ponowienie próby.
• Maildroppa nie podąża za przekierowaniami ani innymi odpowiedziami 3xx i traktuje je jako błędy kończące dostarczenie.
• Pozostałe odpowiedzi 4xx są traktowane jako błędy kończące dostarczenie i nie powodują ponowienia próby.

Zwracaj 200, 202 lub 204 tylko wtedy, gdy zdarzenie zostało bezpiecznie przyjęte. Jeśli przetwarzanie jest czasochłonne, najpierw zapisz zdarzenie i zwróć odpowiedź oznaczającą powodzenie, a następnie wykonaj wolniejsze operacje asynchronicznie.

Nie zwracaj przekierowania na inny adres URL webhooka. Zamiast tego skonfiguruj końcowy adres URL w Maildroppa.

Harmonogram automatycznych ponowień

Dla dostarczenia produkcyjnego można wykonać maksymalnie siedem prób HTTP.

Po błędzie kwalifikującym się do ponowienia Maildroppa planuje kolejną próbę z następującym opóźnieniem:

1. Po próbie 1: 1 minuta
2. Po próbie 2: 5 minut
3. Po próbie 3: 30 minut
4. Po próbie 4: 2 godziny
5. Po próbie 5: 12 godzin
6. Po próbie 6: 24 godziny

Jeśli próba 7 również zakończy się błędem kwalifikującym się do ponowienia, dostarczenie otrzyma stan „Dead” i nie zostaną zaplanowane kolejne automatyczne próby.

Opóźnienia są liczone od poszczególnych nieudanych prób. Rzeczywiste dostarczenie może nastąpić nieco później, ponieważ dostarczenia są przetwarzane asynchronicznie i podlegają również limitom chroniącym system.

W miarę możliwości usuń tymczasowy problem po stronie odbiornika przed terminem widocznym w „Next retry”. Jeśli automatyczne próby się zakończyły, użyj „Replay”, gdy odbiornik znów będzie działał prawidłowo.

Historia dostarczeń

Historia dostarczeń dotyczy aktualnie wybranego endpointu. Jego adres URL pojawia się w nagłówku sekcji, dzięki czemu możesz sprawdzić, którą historię przeglądasz.

Korzystaj z następujących filtrów:

• All — pokazuje dostarczenia produkcyjne i testowe.
• Production — pokazuje tylko dostarczenia rzeczywistych zdarzeń produkcyjnych.
• Test — pokazuje tylko testy uruchomione ręcznie.

Kliknij „Refresh”, aby pobrać aktualny stan. Historia nie musi pozostawać otwarta, gdy Maildroppa wysyła dostarczenie lub ponawia próbę.

Strona pokazuje 50 najnowszych dostarczeń pasujących do wybranego filtra.

Kolumny historii dostarczeń

Każdy wiersz zawiera:

• Created — czas utworzenia rekordu dostarczenia.
• State — stan: Pending, Success, Failed lub Dead.
• HTTP — status odpowiedzi, liczbę prób, czas trwania i termin kolejnej próby, jeśli została zaplanowana.
• Subscriber — adres e-mail subskrybenta, jeśli zdarzenie jest z nim powiązane.
• Delivery — typ zdarzenia, Event ID i Delivery ID.
• Actions — opcję Replay, jeśli dostarczenie kwalifikuje się do ponownej wysyłki.

Jeśli nie wykonano żądania HTTP, kolumna „HTTP” pokazuje „No HTTP attempt”. Może się tak zdarzyć, gdy Maildroppa odrzuci żądanie przed wysłaniem, na przykład z powodu braku sekretu do podpisywania lub braku możliwości bezpiecznego użycia zapisanego adresu docelowego.

Jeśli są dostępne, wiersz pokazuje także „Error” i „Response excerpt” — informacje o błędzie i fragment odpowiedzi odbiornika. Nie zwracaj sekretów ani poufnych danych osobowych w treści odpowiedzi webhooka, ponieważ jej część może pojawić się w logu dostarczeń konta.

Stany dostarczeń

Pending oznacza, że dostarczenie oczekuje na pierwszą próbę lub zaplanowane ponowienie. „Next retry” pojawia się, gdy zaplanowano kolejną próbę.

Success oznacza, że odbiornik zwrócił odpowiedź 2xx. Kolejna automatyczna próba nie jest potrzebna.

Failed oznacza, że dostarczenie zakończyło się problemem niekwalifikującym się do ponowienia, zostało odrzucone przed próbą HTTP lub zatrzymane przed wysłaniem.

Dead oznacza, że wykorzystano wszystkie automatyczne próby dla problemu kwalifikującego się do ponowienia, ale nie otrzymano odpowiedzi oznaczającej powodzenie.

Okres przechowywania historii

Rekordy dostarczeń są przechowywane przez ograniczony czas:

• Pomyślne dostarczenia produkcyjne: 30 dni
• Nieudane dostarczenia produkcyjne: 90 dni
• Dostarczenia produkcyjne w stanie Dead: 90 dni
• Dostarczenia testowe: 30 dni

Jeśli potrzebujesz dłuższej historii audytowej, prowadź własne logi integracji. Zapisuj Event ID i Delivery ID, ale unikaj niepotrzebnego przechowywania sekretów.

Ponownie wyślij dostarczenie

Kliknij „Replay”, aby ponowić próbę dla zakończonego dostarczenia produkcyjnego.

Opcja „Replay” jest dostępna dla dostarczeń produkcyjnych w stanie „Success”, „Failed” lub „Dead”. Nie jest dostępna w stanie „Pending”. Dostarczeń testowych nie można wysłać ponownie.

Ponowna wysyłka:

• Tworzy nowe dostarczenie w stanie Pending.
• Tworzy nowy Delivery ID.
• Zachowuje pierwotny Event ID.
• Zachowuje pierwotny typ zdarzenia i ładunek JSON.
• Korzysta z pierwotnego zapisanego adresu docelowego URL i migawki niestandardowych nagłówków.
• Korzysta z bieżącego sekretu do podpisywania w chwili przygotowywania nowego żądania.

Funkcja „Replay” nie tworzy ładunku na nowo na podstawie aktualnych danych subskrybenta. Wysyła ponownie pierwotną migawkę zdarzenia. Dzięki temu ponowną wysyłkę można objąć audytem, a znaczenie historycznego zdarzenia nie zmienia się niepostrzeżenie.

W danym momencie tylko jedna ponowna wysyłka tego samego dostarczenia źródłowego może mieć stan „Pending”. Poczekaj na jej zakończenie, zanim zlecisz kolejną.

Przed ponowną wysyłką upewnij się, że endpoint jest aktywny. Jeśli jest nieaktywny, ponowna wysyłka umieszczona w kolejce nie może zakończyć się pomyślnym dostarczeniem.

Odbiornik mógł wykonać operację biznesową, nawet jeśli do Maildroppa nie dotarła odpowiedź oznaczająca powodzenie. Ponowna wysyłka może więc spowodować powtórzenie żądania. Deduplikacja według Event ID chroni połączony system przed ponownym wykonaniem tej samej operacji.

Edytuj endpoint

Kliknij „Edit”, aby zmienić adres URL, wybór zdarzeń, niestandardowe nagłówki lub status aktywności.

Przed zapisaniem sprawdź konfigurację i wykonaj poniższe kroki:

1. Upewnij się, że nowy adres URL jest już dostępny.
2. Pozostaw pola zapisanych wartości nagłówków puste, jeśli wartości mają pozostać bez zmian.
3. Wprowadź nową wartość dla każdego nagłówka, którego nazwa została zmieniona.
4. Sprawdź wybór zdarzeń, aby przypadkowo nie wyłączyć potrzebnych powiadomień.
5. Zapisz zmiany i wyślij nowy testowy webhook.

Pamiętaj, że dostarczenia w kolejce zachowują dotychczasową migawkę adresu URL i niestandardowych nagłówków. Przetestuj nową konfigurację z myślą o przyszłych dostarczeniach. Nie zakładaj, że zmieni ona starsze żądania w kolejce.

Dezaktywuj endpoint

Użyj przełącznika „On/Off”, aby wstrzymać integrację bez usuwania jej konfiguracji i historii.

Po wyłączeniu endpointu:

• Nowe zdarzenia nie trafiają już do jego kolejki.
• Oczekujące dostarczenia, które nie zostały jeszcze pobrane do wysłania, otrzymują stan Failed.
• Opcja Test zostaje wyłączona.
• Endpoint nadal można edytować i później aktywować.

Żądanie będące już w trakcie realizacji w chwili dezaktywacji może się jeszcze zakończyć. Jeśli ma to znaczenie dla integracji, po wyłączeniu endpointu sprawdź historię dostarczeń.

Zdarzenia pominięte w czasie, gdy endpoint był nieaktywny, nie są wysyłane po jego ponownej aktywacji.

Usuń endpoint

Jeśli endpoint nie jest już potrzebny, kliknij „Delete” i potwierdź operację w oknie ostrzeżenia.

Usunięcie endpointu usuwa go ze strony, zatrzymuje przyszłe dostarczenia zdarzeń i nadaje stan „Failed” oczekującym dostarczeniom, które nie zostały jeszcze pobrane do wysłania.

Opcja „Delete” nie służy do tymczasowego wstrzymywania integracji. Użyj przełącznika „On/Off”, jeśli konfiguracja lub dostępna historia mogą być jeszcze potrzebne.

Przed usunięciem zapisz wszystkie identyfikatory Event ID i Delivery ID, których nadal potrzebujesz do audytu integracji.

Rozwiązywanie problemów

Nie można zapisać endpointu

Sprawdź, czy:

• Adres URL zaczyna się od https://.
• Adres URL używa publicznej nazwy hosta i portu 443.
• Adres URL nie zawiera zmiennych, danych logowania ani fragmentu.
• Wybrano co najmniej jedno zdarzenie.
• Każdy niestandardowy nagłówek ma unikalną nazwę oraz podaną wartość.
• Zarezerwowane nazwy nagłówków Maildroppa i HTTP nie są używane jako nazwy nagłówków niestandardowych.

Opcja Test jest wyłączona

Opcja „Test” jest dostępna tylko dla aktywnego endpointu. Włącz endpoint przełącznikiem lub edytuj go i zaznacz „Active”, a następnie zapisz zmiany przed testem.

Test pokazuje brak próby HTTP

Jeśli widzisz stan „Missing”, wygeneruj sekret do podpisywania. Sprawdź także, czy docelowa nazwa hosta jest publiczna i nadal jest prawidłowo rozwiązywana na adres IP.

Żądanie może zostać odrzucone przed wysłaniem, jeśli sekret, adres URL lub niestandardowe nagłówki są nieprawidłowe albo cel nie przejdzie kontroli bezpieczeństwa.

Odbiornik zwraca 401 lub 403

Sprawdź zapisaną nazwę niestandardowego nagłówka i dane uwierzytelniające. Jeśli wartość się zmieniła, edytuj endpoint i wprowadź ją ponownie.

Sprawdź też, czy odbiornik nie myli własnych danych uwierzytelniających API z podpisem Maildroppa. Niestandardowy nagłówek autoryzacji i X-Maildroppa-Signature służą różnym celom i mogą być weryfikowane niezależnie.

Odbiornik zwraca przekierowanie

Maildroppa nie podąża za przekierowaniami. Zastąp adres URL endpointu końcowym publicznym adresem HTTPS i przetestuj ponownie.

Podpis się nie zgadza

Upewnij się, że odbiornik:

• Używa bieżącego sekretu do podpisywania.
• Używa dokładnej wartości X-Maildroppa-Timestamp.
• Podpisuje <timestamp>.<raw request body>.
• Używa HMAC-SHA256 i wyniku w zapisie szesnastkowym z małymi literami.
• Porównuje pełną wartość wraz z v1=.
• Wykonuje porównanie, zanim parsowanie JSON zmieni treść żądania.

To samo zdarzenie przychodzi więcej niż raz

Może się tak zdarzyć po przerwaniu połączenia sieciowego, automatycznym ponowieniu próby lub ręcznej ponownej wysyłce. Systemy dostarczania webhooków zwykle działają według modelu „co najmniej raz”, a nie „dokładnie raz”.

Używaj Event ID jako klucza idempotencji. Gdy ponownie otrzymasz już przetworzony Event ID i nie jest potrzebna dodatkowa operacja, zwróć odpowiedź 2xx.

Dostarczenie ma stan Pending

Sprawdź „Next retry” w kolumnie „HTTP”. Po błędzie 408, 429, 5xx kwalifikującym się do ponowienia lub po tymczasowym błędzie sieciowym dostarczenie pozostaje w stanie „Pending” do następnej zaplanowanej próby.

Po upływie terminu ponowienia kliknij „Refresh”, aby pobrać aktualny stan.

Dostarczenie ma stan Dead

Wykorzystano wszystkie automatyczne próby. Najpierw napraw odbiornik, upewnij się, że endpoint jest aktywny, wyślij testowy webhook, a następnie użyj „Replay” dla dostarczenia produkcyjnego.

Lista kontrolna przed uruchomieniem produkcyjnym

Zanim zaczniesz polegać na endpoincie w środowisku produkcyjnym, sprawdź wszystkie poniższe punkty:

1. Odbiornik korzysta ze stabilnego publicznego adresu HTTPS z prawidłowym certyfikatem.
2. Sekret do podpisywania jest przechowywany poza kodem źródłowym.
3. Podpis jest weryfikowany na podstawie niezmienionej, surowej treści żądania.
4. Stare znaczniki czasu są odrzucane zgodnie z udokumentowanym przedziałem tolerancji.
5. Odbiornik zapisuje Event ID i przeprowadza deduplikację na ich podstawie.
6. Odbiornik zapisuje w logach Event ID i Delivery ID na potrzeby śledzenia.
7. Czasochłonne przetwarzanie odbywa się po przyjęciu i trwałym zapisaniu zdarzenia.
8. Odpowiedź 2xx jest zwracana tylko dla przyjętych zdarzeń.
9. Niestandardowe dane uwierzytelniające są przechowywane w nagłówkach, a nie w adresie URL.
10. Wybrane są tylko potrzebne typy zdarzeń.
11. Testowy webhook kończy się powodzeniem i prawidłowo pojawia się w historii dostarczeń.
12. Monitoring powiadamia, gdy dostarczenia produkcyjne zaczynają zwracać błędy.

Po wdrożeniu tych zabezpieczeń strona „Webhooks” zapewnia oba elementy niezawodnej integracji: bezpieczne dostarczanie zdarzeń do aplikacji i przejrzystą historię działania w Maildroppa.