Konfigurowanie webhooków

Published: 16 lipca 2026 · Last updated: 21 lipca 2026 · By Marcus Biel

Webhooki pozwalają Maildroppa powiadamiać inną aplikację, gdy na Twoim koncie wydarzy się coś ważnego.

Zamiast wielokrotnie pytać Maildroppa, czy subskrybent został utworzony, zaktualizowany, wypisany lub otrzymał tag, Twoja aplikacja może otrzymać żądanie HTTPS wkrótce po wystąpieniu zdarzenia.

Strona Webhooks jest centralnym miejscem zarządzania tą integracją na poziomie całego konta. Możesz utworzyć kilka endpointów, wybrać zdarzenia otrzymywane przez każdy endpoint, 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 według następującego procesu:

1. W Maildroppa zachodzi zdarzenie, na przykład utworzenie subskrybenta.
2. Maildroppa wyszukuje każdy aktywny endpoint subskrybujący to zdarzenie.
3. Maildroppa tworzy jedno dostarczenie dla każdego pasującego endpointu.
4. Ładunek JSON jest podpisywany przy użyciu webhookowego sekretu Signing secret Twojego konta.
5. Maildroppa wysyła żądanie HTTPS POST na zapisany adres URL endpointu.
6. Twój 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 tymczasowych błędów.

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

Webhooki konta różnią się od kroku „Send a webhook” wewnątrz 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 używają webhookowego sekretu Signing secret konta, dlatego jego rotacja wpływa na wszystkich odbiorców wychodzących webhooków, którzy weryfikują podpisy Maildroppa.

Otwieranie strony Webhooks

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

Strona zawiera trzy główne obszary:

• Signing secret
• Endpoints
• Historia dostarczeń dla wybranego endpointu

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

Zanim utworzysz endpoint

Przygotuj odbiornik na swoim serwerze przed skonfigurowaniem Maildroppa. Odbiornik powinien:

• Być dostępny przez publiczny adres HTTPS.
• Akceptować żądania POST z treścią application/json.
• Zachować surowe ciało żądania do czasu zweryfikowania podpisu Maildroppa.
• Zwracać status 2xx dopiero po bezpiecznym zaakceptowaniu zdarzenia.
• Idempotentnie przetwarzać powtarzające się dostarczenia, używając Event ID.
• Odpowiadać szybko, zamiast wykonywać powolne operacje podczas żądania.

Niezawodny wzorzec polega na zweryfikowaniu żądania, zapisaniu Event ID i ładunku w trwałej kolejce lub bazie danych, zwróceniu 200 albo 204, a następnie przetworzeniu działania biznesowego.

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

Krok 1: wygeneruj Signing secret

Każde żądanie webhooka Maildroppa jest podpisane. Twój odbiornik używa Signing secret, aby zweryfikować, że żądanie zostało utworzone przez Maildroppa i że treść nie została zmieniona podczas przesyłania.

U góry strony panel Signing secret pokazuje jeden z następujących stanów:

• Missing — Nie istnieje jeszcze żaden Signing secret.
• Ready — Signing secret jest skonfigurowany.
• Loading — Maildroppa pobiera bieżący stan.

Kliknij „Generate secret”, gdy stan to Missing.

Maildroppa natychmiast wyświetla nowy sekret. Zaczyna się on od whsec_. Kliknij „Copy” i przechowuj go w menedżerze sekretów lub chronionej konfiguracji środowiska używanej przez odbiornik.

Pełna wartość jest wyświetlana wyłącznie bezpośrednio po wygenerowaniu lub rotacji. Po ponownym załadowaniu strony lub jej opuszczeniu Maildroppa pokazuje tylko informację, że sekret istnieje, oraz kiedy został ostatnio zaktualizowany. Nie ujawnia ponownie zapisanego sekretu.

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 przechowuje obu wartości przez okres przejściowy. Zaktualizuj każdy odbiornik korzystający z tego sekretu konta przed wysłaniem kolejnych testów lub poleganiem na dostarczeniach produkcyjnych.

Nowe dostarczenia, zaplanowane ponowienia prób, testy i ponowne wysłania są podpisywane bieżącym sekretem w chwili żądania HTTP. Oznacza to, że dostarczenie utworzone przed rotacją może zostać podpisane nowym sekretem, gdy próba jego wysłania nastąpi później.

Traktuj sekret jak hasło

Nie umieszczaj Signing secret w kodzie przeglądarkowym, publicznym repozytorium, adresie URL, stronie błędu ani zwykłym logu aplikacji.

Tylko odbiornik po stronie serwera potrzebuje tego sekretu. Jeśli uważasz, że został ujawniony, natychmiast dokonaj jego rotacji i zaktualizuj wszystkich odbiorców.

Weryfikowanie podpisu 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 wyrażony w sekundach uniksowych.
• X-Maildroppa-Signature — Wersjonowany podpis HMAC.

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ść to znacznik czasu, następnie kropka, a potem dokładne surowe ciało żądania JSON:

<timestamp>.<raw request body>

Użyj Signing secret jako klucza HMAC.

Poniższy przykład w Node.js pokazuje podstawowy etap weryfikacji. rawBody musi być oryginalnymi bajtami żądania, a nie JSON-em, 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 również znacznik czasu z czasem serwera. Odrzucaj żądania wykraczające poza krótki margines tolerancji wybrany dla Twojej infrastruktury, na przykład pięć minut. Zmniejsza to ryzyko, że przechwycone prawidłowe żądanie zostanie odtworzone znacznie później.

Parsuj i przetwarzaj JSON dopiero po pomyślnym przejściu obu kontroli.

Najczęstsze przyczyny błędów podpisu

Podpis zwykle nie przechodzi weryfikacji 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 ciało 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 kodowany inaczej niż małe litery w systemie szesnastkowym.

Gdy weryfikacja się nie powiedzie, rejestruj Event ID i Delivery ID, ale nigdy nie rejestruj Signing secret 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
• Events
• Custom headers
• Active status

Nowe endpointy są domyślnie aktywne, a wszystkie zdarzenia pokazane w edytorze są początkowo zaznaczone. Przejrzyj zaznaczenie przed zapisaniem, aby odbiornik otrzymywał wyłącznie potrzebne powiadomienia.

Konfigurowanie adresu URL endpointu

Wprowadź pełny publiczny adres URL, który powinien otrzymywać żą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, surowego adresu IP ani nazwy hosta, która rozwiązuje się do zablokowanej prywatnej lub zarezerwowanej sieci.

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ń. Zamiast tego użyj Custom header.

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

Nazwa hosta docelowego jest ponownie rozwiązywana przed wysłaniem. Nazwa hosta, która później rozwiąże się do prywatnego lub zablokowanego adresu, zostanie odrzucona, nawet jeśli była prawidłowa w chwili zapisywania endpointu.

Wybieranie zdarzeń

Wybierz co najmniej jedno zdarzenie. Endpoint otrzymuje wyłącznie typy zdarzeń wybrane w jego edytorze.

Strona oferuje następujące opcje zdarzeń:

Subscriber Created — subscriber.created

Wysyłane, gdy subskrybent zostanie utworzony 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 interpretuj tego zdarzenia jako dowodu, że każda rejestracja zakończyła Double Opt-in. Status subskrybenta w ładunku opisuje jego bieżący stan.

Subscriber Updated — subscriber.updated

Wysyłane, gdy zmienią się wbudowane informacje o subskrybencie lub wartości pól niestandardowych.

Użyj pełnego obiektu subskrybenta w ładunku jako bieżącej reprezentacji w Maildroppa. Nie zakładaj, że zmieniła się tylko jedna konkretna właściwość.

Przypisania i usunięcia tagów mają własne typy zdarzeń, dzięki czemu można je obsługiwać oddzielnie.

Subscriber Unsubscribed — subscriber.unsubscribed

Wysyłane, gdy subskrybent przejdzie do stanu unsubscribed w wyniku działania wypisania.

Użyj tego zdarzenia, aby wyciszyć kontakt w połączonych systemach. Nie zapisuj automatycznie tej osoby ponownie, ponieważ inny system nadal oznacza kontakt jako aktywny.

Tag Added — subscriber.tag_added

Wysyłane, gdy tag zostanie przypisany subskrybentowi.

Ładunek zawiera subskrybenta i tag dotyczący tej konkretnej zmiany.

Tag Removed — subscriber.tag_removed

Wysyłane, gdy tag zostanie usunięty z subskrybenta.

Ładunek zawiera zaktualizowanego 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 rejestracyjny Maildroppa.

Traktuj to jako sygnał przesłania formularza, a nie potwierdzenie ukończenia Double Opt-in. Każdy przepływ wymagający potwierdzonej subskrypcji musi nadal uwzględniać bieżący status subskrybenta i proces potwierdzenia.

Używaj osobnych endpointów, gdy różnią się zakresy odpowiedzialności

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

• Wysyłaj zdarzenia subskrybentów i tagów do CRM.
• Wysyłaj zdarzenia wypisania do usługi wyciszania.
• 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 wybór zdarzeń, adres URL, niestandardowe nagłówki, status aktywności, testy i historię dostarczeń.

Dodawanie niestandardowych nagłówków

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ź Header name i Header value. Odpowiednie przykłady:

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ą używać prawidłowych znaków nazwy nagłówka HTTP.
• Muszą być unikalne niezależnie od użycia 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 mogą zostać zastąpione niestandardowym nagłówkiem:

• 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 niestandardową wartością.

Jak przechowywane są sekrety nagłówków

Maildroppa szyfruje wartości niestandardowych nagłówków przed ich zapisaniem. Zapisane wartości nie są zwracane do przeglądarki w formie możliwej do odczytania.

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

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

Usunięcie wiersza nagłówka usuwa ten nagłówek z przyszłych dostarczeń po zapisaniu endpointu.

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

Ustawianie endpointu jako aktywnego lub nieaktywnego

Pozostaw zaznaczoną opcję „Active”, gdy endpoint ma być od razu gotowy do odbierania zdarzeń.

Usuń zaznaczenie, gdy chcesz zapisać konfigurację bez rozpoczynania dostarczeń. Endpoint możesz aktywować później z listy endpointów.

Nieaktywny endpoint:

• Nie otrzymuje nowo występujących zdarzeń.
• Nie może wysłać testowego webhooka.
• Pozostaje widoczny i możliwy do edycji.
• Zachowuje dostęp do istniejącej historii dostarczeń.

Aktywowanie endpointu nie uzupełnia zdarzeń, które wystąpiły, gdy był nieaktywny.

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

Rozumienie listy endpointów

Każdy wiersz endpointu pokazuje:

• Docelowy adres URL.
• Odznakę 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 — Wysyła jedno natychmiastowe żądanie testowe do aktywnego endpointu.
• Edit — Zmienia adres URL, zdarzenia, nagłówki lub status aktywności.
• Delete — Trwale usuwa konfigurację endpointu po potwierdzeniu.

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 tworzy dostarczenie 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 utworzone dostarczenia. Dostarczenie, które już znajdowało się w kolejce, zachowuje pierwotne miejsce docelowe i zapisaną konfigurację nagłówków.

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

Signing secret działa inaczej: jest odczytywany podczas przygotowywania żądania HTTP. Oczekujące dostarczenie lub ponowne wysłanie może więc użyć nowo obróconego Signing secret, nawet jeśli jego ładunek i migawka endpointu zostały utworzone wcześniej.

Testowanie endpointu

Kliknij „Test” przy aktywnym endpoincie, gdy odbiornik i Signing secret są gotowe.

Maildroppa natychmiast wysyła jedno podpisane żądanie przy użyciu 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 różnią się dla każdego rzeczywistego testu.

Test wykonuje dokładnie jedną próbę HTTP. Dostarczenia testowe nie są umieszczane w produkcyjnym harmonogramie ponowień i nie można ich ponownie wysłać.

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

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

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

Rozumienie ładunku produkcyjnego

Produkcyjne zdarzenia konta używają wspólnej koperty 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 oznaczają:

• id — Event ID. Pasuje do X-Maildroppa-Event-Id.
• type — Klucz zdarzenia wybrany w edytorze endpointu.
• schema_version — Wersja schematu ładunku. Używaj jej przy decydowaniu, jak analizować zdarzenie.
• 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 według dokładnej wartości type. Ignoruj dodatkowe właściwości, których integracja nie potrzebuje, aby kompatybilne rozszerzenia ładunku nie powodowały awarii odbiornika.

Ładunek zdarzenia subskrybenta

Zdarzenia subskrybenta zawierają bieżącą reprezentację subskrybenta 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. Mogą być puste. Właściwość subskrybenta może również mieć wartość null, gdy nie istnieje żadna wartość, dlatego odbiornik powinien postępować zgodnie ze schematem ładunku, zamiast zakładać obecność każdej opcjonalnej wartości profilu.

Ładunek zdarzenia tagu

Zdarzenia tagów zawierają zarówno subskrybenta, jak i tag, który spowodował 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 element 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. Pojawia się w:

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

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

Ponowienia prób i ręczne ponowne wysłania również zachowują pierwotny Event ID. Przechowuj przetworzone Event ID i zapewnij idempotencję działania biznesowego, aby powtórne żądanie nie tworzyło duplikatów kontaktów, nie powtarzało nieodwracalnej operacji ani nie stosowało tej samej zmiany dwukrotnie.

Delivery ID

Delivery ID identyfikuje jeden rekord dostarczenia. Pojawia się w:

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

Każde dostarczenie do endpointu ma własny Delivery ID. Ręczne ponowne wysłanie tworzy nowy Delivery ID, zachowując pierwotny Event ID.

Używaj Delivery ID do śledzenia technicznego i wsparcia. Używaj Event ID do deduplikacji na poziomie biznesowym.

Zwracanie prawidłowej odpowiedzi HTTP

Maildroppa klasyfikuje odpowiedzi w następujący sposób:

• Każda odpowiedź 2xx oznacza pomyślne dostarczenie.
• Odpowiedzi 408 Request Timeout, 429 Too Many Requests i 5xx są tymczasowymi błędami i mogą być ponawiane.
• Tymczasowe błędy sieciowe są ponawiane.
• Przekierowania i inne odpowiedzi 3xx nie są śledzone i są traktowane jako błędy końcowe.
• Inne odpowiedzi 4xx są traktowane jako błędy końcowe i nie są ponawiane.

Zwracaj 200, 202 lub 204 tylko wtedy, gdy zdarzenie zostało bezpiecznie zaakceptowane. Jeśli przetwarzanie zajmuje czas, najpierw zapisz zdarzenie i zwróć odpowiedź powodzenia, a dopiero potem wykonaj wolniejsze operacje asynchronicznie.

Nie zwracaj przekierowania do innego adresu URL webhooka. Zamiast tego skonfiguruj końcowy adres URL w Maildroppa.

Automatyczny harmonogram ponowień

Produkcyjne dostarczenia mogą wykonać maksymalnie siedem prób HTTP.

Po błędzie możliwym do ponowienia Maildroppa planuje kolejną próbę z następującymi opóźnieniami:

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 nadal zakończy się błędem możliwym do ponowienia, dostarczenie otrzymuje stan Dead i nie jest planowana żadna kolejna automatyczna próba.

Harmonogram jest liczony od poszczególnych nieudanych prób. Rzeczywisty czas dostarczenia może być nieco późniejszy, ponieważ dostarczenia są przetwarzane asynchronicznie i podlegają również limitom ochrony systemu.

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

Rozumienie historii dostarczeń

Historia dostarczeń należy do aktualnie wybranego endpointu. Adres URL endpointu pojawia się w nagłówku sekcji, aby można było potwierdzić, którą historię oglądasz.

Używaj następujących filtrów:

• All — Pokazuje dostarczenia produkcyjne i testowe.
• Production — Pokazuje wyłącznie dostarczenia zdarzeń na żywo.
• Test — Pokazuje wyłącznie ręczne testy.

Kliknij „Refresh”, aby pobrać najnowszy stan. Historia nie musi pozostać otwarta podczas wysyłania lub ponawiania dostarczenia przez Maildroppa.

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

Kolumny dostarczeń

Każdy wiersz zawiera:

• Created — Kiedy utworzono rekord dostarczenia.
• State — Pending, Success, Failed lub Dead.
• HTTP — Status odpowiedzi, liczba prób, czas trwania oraz czas następnej próby, gdy ma zastosowanie.
• Subscriber — Adres e-mail subskrybenta, gdy zdarzenie jest z nim powiązane.
• Delivery — Typ zdarzenia, Event ID i Delivery ID.
• Actions — Replay, gdy dostarczenie się do tego kwalifikuje.

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 gdy brakuje Signing secret lub zapisane miejsce docelowe nie może być już bezpiecznie użyte.

Gdy są dostępne, wiersz pokazuje również Error i Response excerpt zwrócone przez odbiornik. Nie zwracaj sekretów ani poufnych danych osobowych w treści odpowiedzi webhooka, ponieważ jej część może pojawić się w dzienniku 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. Nie jest wymagana kolejna automatyczna próba.

Failed oznacza, że dostarczenie zakończyło się problemem, którego nie można ponowić, zostało odrzucone przed próbą HTTP lub zatrzymano je przed wysłaniem.

Dead oznacza, że wykorzystano wszystkie automatyczne próby w przypadku problemu możliwego do ponowienia, nie otrzymując pomyślnej odpowiedzi.

Przechowywanie 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

Prowadź własne logi integracji, gdy potrzebujesz dłuższej historii audytowej. Przechowuj Event ID i Delivery ID, ale unikaj niepotrzebnego przechowywania sekretów.

Ponowne wysyłanie dostarczenia

Kliknij „Replay”, gdy zakończone dostarczenie produkcyjne powinno zostać podjęte ponownie.

Replay jest dostępne dla dostarczeń produkcyjnych w stanie Success, Failed lub Dead. Nie jest dostępne, gdy dostarczenie ma stan Pending, a dostarczeń testowych nie można ponownie wysyłać.

Ponowne wysłanie:

• Tworzy nowe dostarczenie Pending.
• Tworzy nowy Delivery ID.
• Zachowuje pierwotny Event ID.
• Zachowuje pierwotny typ zdarzenia i ładunek JSON.
• Używa pierwotnego zapisanego docelowego adresu URL i migawki niestandardowych nagłówków.
• Używa bieżącego Signing secret podczas przygotowywania nowego żądania.

Replay nie odtwarza ładunku na podstawie bieżących danych subskrybenta. Ponownie wysyła pierwotną migawkę zdarzenia. Dzięki temu ponowne wysłanie jest możliwe do prześledzenia i zapobiega cichej zmianie znaczenia historycznego zdarzenia.

W danym momencie może oczekiwać tylko jedno ponowne wysłanie tego samego dostarczenia źródłowego. Poczekaj na jego zakończenie przed zleceniem kolejnego.

Przed ponownym wysłaniem upewnij się, że endpoint jest aktywny. Jeśli endpoint jest nieaktywny, zakolejkowane ponowne wysłanie nie może zostać pomyślnie dostarczone.

Ponieważ odbiornik mógł ukończyć działanie biznesowe, nawet jeśli Maildroppa nie otrzymał odpowiedzi powodzenia, ponowne wysłanie może spowodować duplikat żądania. Deduplikacja według Event ID chroni połączony system przed powtórzeniem działania.

Edycja endpointu

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

Przed zapisaniem:

1. Potwierdź, że nowy adres URL jest już dostępny.
2. Pozostaw zapisane wartości nagłówków puste, gdy powinny pozostać bez zmian.
3. Wprowadź nową wartość dla każdego przemianowanego nagłówka.
4. Przejrzyj wybór zdarzeń, aby przypadkowo nie usunąć wymaganych powiadomień.
5. Zapisz zmiany i wyślij nowy testowy webhook.

Pamiętaj, że zakolejkowane dostarczenia zachowują istniejącą migawkę adresu URL i niestandardowych nagłówków. Przetestuj nową konfigurację dla przyszłych dostarczeń, zamiast zakładać, że zmieni ona starsze żądanie znajdujące się w kolejce.

Dezaktywowanie endpointu

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

Gdy endpoint zostanie wyłączony:

• Nowe zdarzenia nie są już dla niego kolejkowane.
• Oczekujące dostarczenia, które nie zostały jeszcze przejęte do wysłania, otrzymują stan Failed.
• Test zostaje wyłączony.
• Endpoint pozostaje dostępny do edycji i późniejszej aktywacji.

Żądanie już trwające w chwili dezaktywacji może nadal się zakończyć. Po wyłączeniu endpointu sprawdź historię dostarczeń, jeśli to rozróżnienie ma znaczenie dla Twojej integracji.

Zdarzenia pominięte, gdy endpoint był nieaktywny, nie są uzupełniane po jego ponownej aktywacji.

Usuwanie endpointu

Kliknij „Delete” i potwierdź ostrzeżenie, gdy endpoint nie powinien już istnieć.

Usunięcie usuwa endpoint ze strony, zatrzymuje przyszłe dostarczenia zdarzeń i oznacza jako Failed oczekujące dostarczenia, które nie zostały jeszcze przejęte do wysłania.

Delete nie służy do tymczasowego wstrzymywania. Użyj przełącznika On/Off, gdy możesz ponownie potrzebować konfiguracji lub widocznej historii.

Przed usunięciem zapisz wszystkie Event ID lub 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 Custom header ma unikalną nazwę i wartość.
• Zarezerwowane nagłówki Maildroppa i HTTP nie są używane jako nazwy niestandardowe.

Test jest wyłączony

Test jest dostępny tylko dla aktywnego endpointu. Włącz endpoint lub edytuj go i wybierz „Active”, a następnie zapisz przed testowaniem.

Test pokazuje brak próby HTTP

Wygeneruj Signing secret, jeśli stan to Missing. Sprawdź również, czy docelowa nazwa hosta jest publiczna i nadal prawidłowo się rozwiązuje.

Żądanie może zostać odrzucone przed wysłaniem, gdy jego sekret, adres URL, niestandardowe nagłówki lub kontrola bezpieczeństwa miejsca docelowego są nieprawidłowe.

Odbiornik zwraca 401 lub 403

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

Sprawdź również, 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ć sprawdzane 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

Potwierdź, że odbiornik:

• Używa bieżącego Signing secret.
• Używa dokładnej wartości X-Maildroppa-Timestamp.
• Podpisuje <timestamp>.<raw request body>.
• Używa HMAC-SHA256 i wyniku w postaci małych liter szesnastkowych.
• Porównuje pełną wartość wraz z v1=.
• Wykonuje porównanie, zanim parsowanie JSON zmieni ciało.

To samo zdarzenie przychodzi więcej niż raz

Może się tak zdarzyć po przerwaniu połączenia sieciowego, ponowieniu próby lub ręcznym ponownym wysłaniu. Systemy dostarczania webhooków zwykle zapewniają dostarczenie co najmniej raz, a nie dokładnie raz.

Używaj Event ID jako klucza idempotencji. Zwracaj odpowiedź 2xx, gdy ponownie otrzymasz już przetworzone Event ID i nie jest wymagane dodatkowe działanie.

Dostarczenie ma stan Pending

Sprawdź „Next retry” w kolumnie HTTP. Możliwy do ponowienia błąd 408, 429, 5xx lub tymczasowy błąd sieci pozostaje w stanie Pending do następnej zaplanowanej próby.

Kliknij „Refresh” po czasie ponowienia, aby załadować najnowszy 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.

Zalecana lista kontrolna dla produkcji

Przed poleganiem na endpoincie w środowisku produkcyjnym potwierdź wszystkie poniższe punkty:

1. Odbiornik używa stabilnego publicznego adresu HTTPS z prawidłowym certyfikatem.
2. Signing secret jest przechowywany poza kodem źródłowym.
3. Podpis jest sprawdzany względem niezmienionego surowego ciała.
4. Stare znaczniki czasu są odrzucane zgodnie z udokumentowanym marginesem tolerancji.
5. Odbiornik przechowuje i deduplikuje Event ID.
6. Odbiornik rejestruje Event ID i Delivery ID na potrzeby śledzenia.
7. Powolne przetwarzanie odbywa się po trwałym zaakceptowaniu zdarzenia.
8. Odpowiedź 2xx jest zwracana wyłącznie dla zaakceptowanych zdarzeń.
9. Niestandardowe dane uwierzytelniające są przechowywane w nagłówkach, a nie w adresie URL.
10. Wybrane są tylko wymagane typy zdarzeń.
11. Testowy webhook kończy się powodzeniem i pojawia się prawidłowo w historii dostarczeń.
12. Monitoring ostrzega, gdy dostarczenia produkcyjne zaczynają zwracać błędy.

Po zastosowaniu tych zabezpieczeń strona Webhooks zapewnia oba elementy niezawodnej integracji: bezpieczne dostarczanie zdarzeń do aplikacji oraz przejrzystą historię operacyjną w Maildroppa.