Konfigurace webhooků

Published: 16. července 2026 · Last updated: 21. července 2026 · By Marcus Biel

Webhooky umožňují Maildroppě upozornit jinou aplikaci, když se ve vašem účtu stane něco důležitého.

Místo opakovaného dotazování Maildroppy, zda byl odběratel vytvořen, aktualizován, odhlášen nebo mu byl přiřazen štítek, může vaše aplikace krátce po události přijmout požadavek HTTPS.

Stránka Webhooks je centrálním místem pro tuto integraci platnou pro celý účet. Můžete vytvořit několik koncových bodů, vybrat události, které má každý z nich přijímat, přidat ověřovací hlavičky, otestovat připojení, prohlédnout si pokusy o doručení a v případě potřeby znovu přehrát produkční událost.

Jak fungují webhooky účtu

Webhook účtu probíhá takto:

1. V Maildroppě dojde k události, například k vytvoření odběratele.
2. Maildroppa vyhledá všechny aktivní koncové body přihlášené k dané události.
3. Maildroppa vytvoří pro každý odpovídající koncový bod jedno doručení.
4. JSON payload je podepsán podpisovým tajemstvím webhooků vašeho účtu.
5. Maildroppa odešle požadavek HTTPS POST na uloženou URL koncového bodu.
6. Váš koncový bod ověří podpis, uloží nebo zpracuje událost a vrátí HTTP odpověď.
7. Maildroppa zaznamená výsledek v historii doručení a automaticky opakuje dočasně neúspěšná doručení.

Pokud je k téže události přihlášeno několik koncových bodů, každý z nich obdrží vlastní doručení. Obchodní událost má u všech stejné ID události, zatímco každé doručení má vlastní ID doručení.

Webhooky účtu se liší od kroku „Odeslat webhook“ uvnitř automatizace. Webhooky účtu naslouchají vybraným událostem účtu napříč Maildroppou. Webhook automatizace se odešle pouze tehdy, když odběratel dosáhne konkrétního kroku. Oba používají podpisové tajemství webhooků účtu, takže změna tajemství ovlivní každý odchozí přijímač webhooků, který ověřuje podpisy Maildroppy.

Otevření stránky Webhooks

Otevřete „Nastavení“, rozbalte „Vývojáři“ a vyberte „Webhooks“.

Stránka obsahuje tři hlavní části:

• Podpisové tajemství
• Koncové body
• Historie doručení pro vybraný koncový bod

Pokud máte více než jeden koncový bod, vyberte řádek koncového bodu a zobrazte jeho historii doručení. Pokud jste žádný výslovně nevybrali, Maildroppa zobrazí historii prvního koncového bodu v seznamu.

Než vytvoříte koncový bod

Než začnete Maildroppu konfigurovat, připravte na svém serveru přijímač. Přijímač by měl:

• Být dostupný prostřednictvím veřejné URL HTTPS.
• Přijímat požadavky POST s tělem application/json.
• Zachovat nezpracované tělo požadavku, dokud nebude ověřen podpis Maildroppy.
• Vrátit stav 2xx až poté, co byla událost bezpečně přijata.
• Zpracovávat opakovaná doručení idempotentně pomocí ID události.
• Odpovídat rychle, místo aby během požadavku prováděl pomalé operace.

Spolehlivým postupem je požadavek ověřit, uložit ID události a payload do trvalé fronty nebo databáze, vrátit 200 nebo 204 a obchodní akci zpracovat později.

Nevystavujte jako produkční přijímač webhooků vývojový počítač, adresu místní sítě ani nechráněný skript. Maildroppa přijímá pouze veřejné cíle HTTPS a při odesílání doručení cíl znovu kontroluje.

Krok 1: Vygenerujte podpisové tajemství

Každý požadavek webhooku Maildroppy je podepsán. Váš přijímač pomocí podpisového tajemství ověřuje, že požadavek vytvořila Maildroppa a že tělo nebylo během přenosu změněno.

Panel Podpisové tajemství v horní části stránky zobrazuje jeden z těchto stavů:

• Chybí — Podpisové tajemství zatím neexistuje.
• Připraveno — Podpisové tajemství je nakonfigurováno.
• Načítání — Maildroppa získává aktuální stav.

Když je stav Chybí, klikněte na „Vygenerovat tajemství“.

Maildroppa nové tajemství okamžitě zobrazí. Začíná řetězcem whsec_. Klikněte na „Kopírovat“ a uložte je do správce tajemství nebo chráněné konfigurace prostředí, kterou váš přijímač používá.

Celá hodnota se zobrazí pouze bezprostředně po vygenerování nebo změně. Po opětovném načtení stránky nebo jejím opuštění Maildroppa zobrazí jen informaci, že tajemství existuje, a kdy bylo naposledy aktualizováno. Uložené tajemství znovu neodhalí.

Pokud tajemství ztratíte

Pokud přijímač již nemá aktuální tajemství, klikněte na „Změnit tajemství“ a uložte nově zobrazenou hodnotu.

Změna okamžitě nahradí předchozí tajemství. Maildroppa obě hodnoty po přechodnou dobu neuchovává. Před odesláním dalších testů nebo spoléháním na produkční doručení aktualizujte každý přijímač, který toto tajemství účtu používá.

Nová doručení, naplánované opakované pokusy, testy a opakovaná přehrání jsou podepisovány aktuálním tajemstvím v okamžiku HTTP požadavku. To znamená, že doručení vytvořené před změnou může být při pozdějším pokusu podepsáno novým tajemstvím.

Zacházejte s tajemstvím jako s heslem

Nevkládejte podpisové tajemství do kódu v prohlížeči, veřejného repozitáře, URL, chybové stránky ani běžného aplikačního logu.

Tajemství potřebuje pouze serverový přijímač. Pokud se domníváte, že bylo odhaleno, okamžitě jej změňte a aktualizujte všechny přijímače.

Ověření podpisu webhooku

Každý požadavek obsahuje tyto hlavičky Maildroppy:

• X-Maildroppa-Event-Id — Identifikuje obchodní událost.
• X-Maildroppa-Delivery-Id — Identifikuje toto konkrétní doručení.
• X-Maildroppa-Timestamp — Čas podpisu v sekundách Unixu.
• X-Maildroppa-Signature — Verziovaný podpis HMAC.

Maildroppa také odesílá:

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

Podpis má tento formát:

v1=<lowercase hexadecimal HMAC>

Maildroppa jej vytváří pomocí HMAC-SHA256. Podepisovaný obsah tvoří časové razítko, za ním tečka a přesné nezpracované tělo požadavku JSON:

<timestamp>.<raw request body>

Jako klíč HMAC použijte podpisové tajemství.

Následující příklad v Node.js ukazuje základní krok ověření. rawBody musí být původními bajty požadavku, nikoli JSON, který již byl analyzován a znovu serializován.

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 ověření podpisu také porovnejte časové razítko s časem serveru. Odmítejte požadavky mimo krátkou toleranci zvolenou pro vaši infrastrukturu, například pět minut. Tím snížíte riziko, že zachycený platný požadavek bude mnohem později znovu přehrán.

JSON analyzujte a zpracovávejte až po úspěšném provedení obou kontrol.

Běžné příčiny chyb podpisu

Podpis obvykle selže z některého z těchto důvodů:

• Po změně se používá staré tajemství.
• Middleware analyzoval nebo změnil JSON před výpočtem podpisu.
• Přijímač podepisuje pouze tělo a vynechává <timestamp>..
• S časovým razítkem se zachází jako s formátovaným datem namísto přesné hodnoty hlavičky.
• Z porovnání je vynechána předpona v1=.
• Vypočítaný HMAC je kódován jinak než malými hexadecimálními znaky.

Při selhání ověření zaznamenejte ID události a ID doručení, nikdy však nezapisujte podpisové tajemství ani citlivé hodnoty vlastních hlaviček.

Krok 2: Přidejte koncový bod

V části Koncové body klikněte na „Přidat koncový bod“.

Editor obsahuje čtyři části:

• URL koncového bodu
• Události
• Vlastní hlavičky
• Aktivní stav

Nové koncové body jsou ve výchozím nastavení aktivní a všechny události zobrazené v editoru jsou zpočátku vybrané. Před uložením výběr zkontrolujte, aby přijímač dostával pouze oznámení, která skutečně potřebuje.

Konfigurace URL koncového bodu

Zadejte úplnou veřejnou URL, která má přijímat požadavky Maildroppy, například:

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

URL musí splňovat tyto požadavky:

• Musí používat https://.
• Musí obsahovat platný veřejný název hostitele.
• Může mít délku až 2 048 znaků.
• Nesmí obsahovat proměnné šablony se znaky { nebo }.
• Nesmí obsahovat uživatelské jméno ani heslo před názvem hostitele.
• Nesmí obsahovat fragment URL začínající znakem #.
• Musí používat standardní port HTTPS 443.
• Nesmí používat localhost, přímou IP adresu ani název hostitele, který se překládá na blokovanou privátní nebo vyhrazenou síť.

Parametry dotazu jsou podporovány, ale do URL nevkládejte klíče API ani jiná tajemství. URL jsou viditelné v seznamu koncových bodů a v datech doručení. Přihlašovací údaje použijte místo toho ve vlastní hlavičce.

Maildroppa nepřesměrování nesleduje. Uložte konečný cíl HTTPS, nikoli URL, která vrací 301, 302, 307 nebo 308.

Název hostitele cíle se před odesláním znovu přeloží. Název hostitele, který se později přeloží na privátní nebo blokovanou adresu, bude odmítnut, i když byl při uložení koncového bodu platný.

Výběr událostí

Vyberte alespoň jednu událost. Koncový bod přijímá pouze typy událostí vybrané v jeho editoru.

Stránka nabízí tyto možnosti událostí:

Odběratel vytvořen — subscriber.created

Odesílá se při vytvoření odběratele v účtu Maildroppa.

Tuto událost použijte k vytvoření odpovídajícího kontaktu v CRM, platformě zákaznických dat, interní databázi nebo jiném systému zohledňujícím oprávnění.

Nevykládejte tuto událost jako důkaz, že každý odběr dokončil dvojité přihlášení. Stav odběratele v payloadu popisuje aktuální stav.

Odběratel aktualizován — subscriber.updated

Odesílá se při změně vestavěných informací o odběrateli nebo hodnot vlastních polí.

Úplný objekt odběratele v payloadu použijte jako aktuální reprezentaci v Maildroppě. Nepředpokládejte, že se změnila pouze jedna konkrétní vlastnost.

Přiřazení a odebrání štítků mají vlastní typy událostí, takže je lze zpracovávat samostatně.

Odběratel odhlášen — subscriber.unsubscribed

Odesílá se, když odběratel přejde do stavu odhlášení prostřednictvím akce odhlášení.

Tuto událost použijte k potlačení kontaktu v propojených systémech. Osobu automaticky znovu nepřihlašujte jen proto, že ji jiný systém stále označuje jako aktivní.

Štítek přidán — subscriber.tag_added

Odesílá se při přiřazení štítku odběrateli.

Payload obsahuje odběratele a štítek, kterých se tato konkrétní změna týká.

Štítek odebrán — subscriber.tag_removed

Odesílá se při odebrání štítku odběrateli.

Payload obsahuje aktualizovaného odběratele a odebraný štítek. Odebraný štítek je uveden samostatně, přestože již není přítomen v aktuálním poli tags odběratele.

Formulář odeslán — form.submitted

Odesílá se při odeslání registračního formuláře Maildroppy návštěvníkem.

Považujte to za signál odeslání formuláře, nikoli za potvrzení dokončení dvojitého přihlášení. Každý pracovní postup vyžadující potvrzený odběr musí nadále respektovat aktuální stav odběratele a proces potvrzení.

Pokud se odpovědnosti liší, použijte samostatné koncové body

Různé události můžete odesílat do různých systémů. Například:

• Události odběratelů a štítků posílejte do CRM.
• Události odhlášení posílejte do služby pro potlačení kontaktů.
• Události odeslání formuláře posílejte do analytického systému.

Samostatné koncové body snižují zbytečný provoz a usnadňují diagnostiku chyb. Každý koncový bod má vlastní výběr událostí, URL, vlastní hlavičky, aktivní stav, testy a historii doručení.

Přidání vlastních hlaviček

Vlastní hlavičky jsou volitelné. Použijte je, pokud přijímač vyžaduje klíč API, token typu bearer, identifikátor tenanta nebo jinou pevnou hlavičku.

Klikněte na „Přidat hlavičku“ a zadejte název a hodnotu hlavičky. Vhodné příklady zahrnují:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Můžete přidat až 20 vlastních hlaviček.

Názvy hlaviček:

• Jsou povinné.
• Mohou obsahovat až 128 znaků.
• Musí používat platné znaky názvu HTTP hlavičky.
• Musí být jedinečné bez ohledu na velikost písmen.

Hodnoty hlaviček:

• Jsou povinné.
• Mohou obsahovat až 2 000 znaků.
• Nesmějí obsahovat zalomení řádků.

Následující názvy jsou vyhrazené a nelze je nahradit vlastní hlavičkou:

• Content-Type
• Content-Length
• Host
• User-Agent
• Jakýkoli název začínající na X-Maildroppa-

Tím se zabrání tomu, aby vlastní hodnota nahradila hlavičky doručení a podpisu Maildroppy.

Jak se ukládají tajemství hlaviček

Maildroppa před uložením hodnoty vlastních hlaviček šifruje. Uložené hodnoty se do prohlížeče nevracejí v čitelné podobě.

Při pozdější úpravě koncového bodu se v poli hodnoty zobrazí „Uložená hodnota zachována“. Pokud má stávající tajemství zůstat beze změny, nechte pole prázdné. Chcete-li je nahradit, zadejte novou hodnotu.

Pokud změníte název hlavičky, zadejte hodnotu znovu. Maildroppa uchovává uložené tajemství pouze tehdy, když jeho původní název hlavičky zůstane nezměněn.

Odebráním řádku hlavičky se tato hlavička po uložení koncového bodu odstraní z budoucích doručení.

S hodnotami vlastních hlaviček se v uložených informacích o požadavcích zachází jako s citlivými údaji. V historii doručení jsou skryté, nikoli zobrazené.

Nastavení aktivního nebo neaktivního koncového bodu

Pokud je koncový bod připraven okamžitě přijímat události, ponechte vybranou možnost „Aktivní“.

Zrušte její výběr, pokud chcete konfiguraci uložit bez zahájení doručování. Koncový bod můžete aktivovat později ze seznamu koncových bodů.

Neaktivní koncový bod:

• Nepřijímá nově vzniklé události.
• Nemůže odeslat testovací webhook.
• Zůstává viditelný a upravitelný.
• Zachovává svou stávající historii doručení.

Aktivace koncového bodu nedoplní události, ke kterým došlo v době jeho neaktivity.

Když jsou URL, výběr událostí, hlavičky a stav správné, klikněte na „Uložit“.

Porozumění seznamu koncových bodů

Každý řádek koncového bodu zobrazuje:

• Cílovou URL.
• Odznak Aktivní nebo Neaktivní.
• Typy přihlášených událostí.
• Počet vlastních hlaviček.
• Čas poslední aktualizace koncového bodu.

Dostupné akce jsou:

• Zap/Vyp — Aktivuje nebo deaktivuje koncový bod.
• Test — Odešle jeden okamžitý testovací požadavek na aktivní koncový bod.
• Upravit — Změní URL, události, hlavičky nebo aktivní stav.
• Smazat — Po potvrzení trvale odstraní konfiguraci koncového bodu.

Výběrem hlavní části řádku otevřete pod seznamem historii doručení daného koncového bodu.

Jak uložené změny ovlivňují existující doručení

Událost účtu vytvoří doručení se snímkem URL koncového bodu, payloadu a vlastních hlaviček platných v daném okamžiku.

Úprava URL nebo vlastních hlaviček ovlivní nově vytvořená doručení. Již zařazené doručení si zachová původní cíl a uloženou konfiguraci hlaviček.

Změna vybraných událostí ovlivní pouze události, ke kterým dojde později. Maildroppa zpětně nevytváří doručení pro typy událostí, které nebyly vybrány v okamžiku vzniku události.

Podpisové tajemství funguje jinak: načítá se při přípravě HTTP požadavku. Čekající doručení nebo opakované přehrání proto může použít nově změněné podpisové tajemství, i když jeho payload a snímek koncového bodu byly vytvořeny dříve.

Testování koncového bodu

Po přípravě přijímače a podpisového tajemství klikněte na aktivním koncovém bodu na „Test“.

Maildroppa okamžitě odešle jeden podepsaný požadavek pomocí uložené URL koncového bodu a uložených vlastních hlaviček. Neuložené změny v otevřeném editoru nejsou součástí testu.

Testovací payload používá typ události webhook.test a nastavuje 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."
  }
}

Vygenerovaná ID a časové razítko se při každém skutečném testu liší.

Test provede přesně jeden pokus HTTP. Testovací doručení nejsou zařazena do produkčního plánu opakování a nelze je znovu přehrát.

Po dokončení požadavku panel s výsledkem zobrazí:

• Test úspěšný nebo Test neúspěšný
• ID události
• Stav HTTP, pokud byla přijata odpověď
• Délku trvání
• ID doručení
• Informace o chybě, pokud jsou k dispozici
• Výňatek z odpovědi, pokud přijímač vrátil tělo

Test se také zobrazí v historii doručení s odznakem Test. Pomocí filtru „Test“ zobrazíte pouze testovací požadavky.

Porozumění produkčnímu payloadu

Produkční události účtu používají společný obal JSON:

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

Vlastnosti nejvyšší úrovně znamenají:

• id — ID události. Odpovídá X-Maildroppa-Event-Id.
• type — Klíč události vybraný v editoru koncového bodu.
• schema_version — Verze schématu payloadu. Použijte ji při rozhodování, jak událost analyzovat.
• created_at — Čas vytvoření payloadu události v UTC.
• livemode — true pro produkční události a false pro testovací události.
• data — Obsah specifický pro danou událost.

Události směrujte podle přesné hodnoty type. Ignorujte další vlastnosti, které vaše integrace nepotřebuje, aby kompatibilní rozšíření payloadu přijímač nerozbila.

Payload události odběratele

Události odběratele obsahují aktuální reprezentaci odběratele uvnitř 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 a tags jsou pole. Mohou být prázdná. Vlastnost odběratele také může být null, pokud neexistuje žádná hodnota, proto by se váš přijímač měl řídit schématem payloadu a nepředpokládat přítomnost každé volitelné profilové hodnoty.

Payload události štítku

Události štítků obsahují odběratele i štítek, který událost způsobil:

{
  "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"
    }
  }
}

U subscriber.tag_removed data.tag stále identifikuje odebraný štítek, i když jej aktuální pole tags odběratele již neobsahuje.

ID událostí, ID doručení a idempotence

ID události a ID doručení slouží k různým účelům.

ID události

ID události identifikuje obchodní událost. Objevuje se v:

• Vlastnosti id na nejvyšší úrovni payloadu.
• Hlavičce požadavku X-Maildroppa-Event-Id.
• Historii doručení.

Stejná událost může být odeslána několika přihlášeným koncovým bodům. Tato doručení sdílejí ID události.

Opakované pokusy i ruční opakovaná přehrání zachovávají původní ID události. Ukládejte zpracovaná ID událostí a zajistěte idempotenci obchodní akce, aby opakovaný požadavek nevytvořil duplicitní kontakty, neopakoval nevratnou akci ani neaplikoval stejnou změnu dvakrát.

ID doručení

ID doručení identifikuje jeden záznam doručení. Objevuje se v:

• Hlavičce požadavku X-Maildroppa-Delivery-Id.
• Historii doručení.

Každé doručení koncovému bodu má vlastní ID doručení. Ruční opakované přehrání vytvoří nové ID doručení, ale zachová původní ID události.

ID doručení používejte pro technické trasování a podporu. ID události používejte pro deduplikaci na obchodní úrovni.

Vrácení správné HTTP odpovědi

Maildroppa klasifikuje odpovědi takto:

• Jakákoli odpověď 2xx označí doručení jako úspěšné.
• Odpovědi 408 Request Timeout, 429 Too Many Requests a 5xx jsou dočasná selhání a lze je opakovat.
• Síťová selhání, která mohou být dočasná, se opakují.
• Přesměrování a jiné odpovědi 3xx se nesledují a jsou považovány za konečná selhání.
• Ostatní odpovědi 4xx jsou považovány za konečná selhání a neopakují se.

200, 202 nebo 204 vracejte pouze tehdy, když byla událost bezpečně přijata. Pokud zpracování trvá, nejprve událost uložte a vraťte úspěšnou odpověď, teprve potom pomalejší práci zpracujte asynchronně.

Nevracejte přesměrování na jinou URL webhooku. Místo toho v Maildroppě nakonfigurujte konečnou URL.

Automatický plán opakování

Produkční doručení mohou provést až sedm pokusů HTTP.

Po opakovatelném selhání Maildroppa naplánuje další pokus s těmito prodlevami:

1. Po pokusu 1: 1 minuta
2. Po pokusu 2: 5 minut
3. Po pokusu 3: 30 minut
4. Po pokusu 4: 2 hodiny
5. Po pokusu 5: 12 hodin
6. Po pokusu 6: 24 hodin

Pokud sedmý pokus stále obdrží opakovatelné selhání, doručení přejde do stavu Mrtvé a další automatický pokus se nenaplánuje.

Plán se měří od jednotlivých neúspěšných pokusů. Skutečný čas doručení může být o něco později, protože doručení jsou zpracovávána asynchronně a podléhají také ochranným limitům systému.

Pokud možno opravte dočasný problém přijímače před zobrazeným časem „Další opakování“. Po skončení automatických pokusů použijte po opětovném zprovoznění přijímače funkci Opakovat.

Porozumění historii doručení

Historie doručení patří aktuálně vybranému koncovému bodu. URL koncového bodu se zobrazuje v záhlaví části, abyste mohli potvrdit, kterou historii si prohlížíte.

Použijte tyto filtry:

• Vše — Zobrazí produkční i testovací doručení.
• Produkce — Zobrazí pouze doručení živých událostí.
• Test — Zobrazí pouze ruční testy.

Kliknutím na „Obnovit“ načtete nejnovější stav. Historii není nutné nechávat otevřenou, zatímco Maildroppa doručení odesílá nebo opakuje.

Stránka zobrazuje 50 nejnovějších odpovídajících doručení pro vybraný filtr.

Sloupce doručení

Každý řádek obsahuje:

• Vytvořeno — Kdy byl záznam doručení vytvořen.
• Stav — Čeká, Úspěch, Selhání nebo Mrtvé.
• HTTP — Stav odpovědi, počet pokusů, trvání a čas dalšího opakování, pokud je relevantní.
• Odběratel — E-mail odběratele, pokud událost s odběratelem souvisí.
• Doručení — Typ události, ID události a ID doručení.
• Akce — Opakovat, pokud je doručení způsobilé.

Pokud nebyl proveden žádný požadavek HTTP, sloupec HTTP zobrazuje „Žádný pokus HTTP“. Může k tomu dojít, když Maildroppa požadavek odmítne před odesláním, například protože chybí podpisové tajemství nebo uložený cíl již nelze bezpečně použít.

Pokud jsou k dispozici, řádek také zobrazuje Chybu a Výňatek z odpovědi vrácené přijímačem. Do těla odpovědi webhooku nevracejte tajemství ani citlivé osobní údaje, protože část této odpovědi se může objevit v protokolu doručení účtu.

Stavy doručení

Čeká znamená, že doručení čeká na první pokus nebo naplánované opakování. Pokud byl naplánován další pokus, zobrazí se „Další opakování“.

Úspěch znamená, že přijímač vrátil odpověď 2xx. Další automatický pokus není nutný.

Selhání znamená, že doručení skončilo neopakovatelným problémem, bylo odmítnuto před pokusem HTTP nebo zastaveno před odesláním.

Mrtvé znamená, že byly vyčerpány všechny automatické pokusy kvůli opakovatelnému problému, aniž by byla přijata úspěšná odpověď.

Uchovávání historie

Záznamy doručení se uchovávají po omezenou dobu:

• Úspěšná produkční doručení: 30 dní
• Neúspěšná produkční doručení: 90 dní
• Mrtvá produkční doručení: 90 dní
• Testovací doručení: 30 dní

Pokud potřebujete delší auditní historii, uchovávejte vlastní protokoly integrace. Ukládejte ID událostí a ID doručení, ale zbytečně neuchovávejte tajemství.

Opakované přehrání doručení

Klikněte na „Opakovat“, pokud má být dokončené produkční doručení odesláno znovu.

Opakované přehrání je dostupné pro produkční doručení ve stavu Úspěch, Selhání nebo Mrtvé. Není dostupné, pokud doručení čeká, a testovací doručení nelze opakovaně přehrát.

Opakované přehrání:

• Vytvoří nové čekající doručení.
• Vytvoří nové ID doručení.
• Zachová původní ID události.
• Zachová původní typ události a payload JSON.
• Použije původní uloženou cílovou URL a snímek vlastních hlaviček.
• Při přípravě nového požadavku použije aktuální podpisové tajemství.

Opakované přehrání znovu nevytváří payload z aktuálních údajů odběratele. Znovu odešle původní snímek události. Díky tomu je opakované přehrání auditovatelné a historická událost nemůže nepozorovaně změnit význam.

U stejného zdrojového doručení může být současně čekající pouze jedno opakované přehrání. Před vyžádáním dalšího počkejte, dokud toto opakované přehrání neskončí.

Před opakováním se ujistěte, že je koncový bod aktivní. Pokud je neaktivní, zařazené opakované přehrání nelze úspěšně doručit.

Protože přijímač mohl obchodní akci dokončit, i když Maildroppa neobdržela jeho úspěšnou odpověď, může opakované přehrání vytvořit duplicitní požadavek. Deduplikace podle ID události chrání propojený systém před opakováním akce.

Úprava koncového bodu

Kliknutím na „Upravit“ změníte URL, výběr událostí, vlastní hlavičky nebo aktivní stav.

Před uložením:

1. Ověřte, že je nová URL již dostupná.
2. Pokud mají uložené hodnoty hlaviček zůstat beze změny, nechte je prázdné.
3. Pro každý přejmenovaný záhlaví zadejte novou hodnotu.
4. Zkontrolujte výběr událostí, aby požadovaná oznámení nebyla omylem odstraněna.
5. Uložte změny a odešlete nový testovací webhook.

Pamatujte, že zařazená doručení zachovávají svou stávající URL a snímek vlastních hlaviček. Novou konfiguraci otestujte pro budoucí doručení a nepředpokládejte, že změní starší zařazený požadavek.

Deaktivace koncového bodu

Přepínač Zap/Vyp použijte, pokud chcete integraci pozastavit bez odstranění její konfigurace a historie.

Když je koncový bod vypnutý:

• Nové události se pro něj již nezařazují.
• Čekající doručení, která ještě nebyla převzata k odeslání, se označí jako Neúspěšná.
• Test je deaktivován.
• Koncový bod zůstává dostupný pro úpravy a pozdější aktivaci.

Požadavek, který právě probíhal v okamžiku deaktivace, může být stále dokončen. Pokud je toto rozlišení pro vaši integraci důležité, po vypnutí koncového bodu zkontrolujte historii doručení.

Události zmeškané v době neaktivity se po opětovném zapnutí nedoplní.

Odstranění koncového bodu

Pokud koncový bod již nemá existovat, klikněte na „Smazat“ a potvrďte varování.

Odstranění odebere koncový bod ze stránky, zastaví budoucí doručování událostí a ukončí čekající doručení, která ještě nebyla převzata k odeslání.

Smazání není způsob dočasného pozastavení. Pokud budete konfiguraci nebo její viditelnou historii možná znovu potřebovat, použijte přepínač Zap/Vyp.

Před odstraněním si poznamenejte ID událostí nebo ID doručení, která ještě potřebujete pro audit integrace.

Řešení problémů

Koncový bod nelze uložit

Zkontrolujte, že:

• URL začíná na https://.
• URL používá veřejný název hostitele a port 443.
• URL neobsahuje proměnné, přihlašovací údaje ani fragment.
• Je vybrána alespoň jedna událost.
• Každá vlastní hlavička má jedinečný název a hodnotu.
• Jako vlastní názvy se nepoužívají vyhrazené hlavičky Maildroppy a HTTP.

Test je deaktivován

Test je dostupný pouze pro aktivní koncový bod. Zapněte koncový bod nebo jej upravte, vyberte „Aktivní“ a před testováním uložte změny.

Test nezobrazuje žádný pokus HTTP

Pokud je stav Chybí, vygenerujte podpisové tajemství. Zkontrolujte také, zda je název hostitele cíle veřejný a zda se stále správně překládá.

Požadavek může být odmítnut před odesláním, pokud je neplatné tajemství, URL, vlastní hlavičky nebo kontrola bezpečnosti cíle.

Přijímač vrací 401 nebo 403

Zkontrolujte uložený název vlastní hlavičky a přihlašovací údaje. Pokud se hodnota změnila, upravte koncový bod a zadejte ji znovu.

Ověřte také, že přijímač nezaměňuje vlastní přihlašovací údaje API s podpisem Maildroppy. Vlastní autorizační hlavička a X-Maildroppa-Signature slouží k různým účelům a lze je kontrolovat nezávisle.

Přijímač vrací přesměrování

Maildroppa přesměrování nesleduje. Nahraďte URL koncového bodu konečnou veřejnou URL HTTPS a test zopakujte.

Podpis nesouhlasí

Ověřte, že přijímač:

• Používá aktuální podpisové tajemství.
• Používá přesnou hodnotu X-Maildroppa-Timestamp.
• Podepisuje <timestamp>.<raw request body>.
• Používá HMAC-SHA256 a výstup malými hexadecimálními znaky.
• Porovnává celou hodnotu včetně v1=.
• Provádí porovnání před tím, než analýza JSON změní tělo.

Stejná událost přichází více než jednou

Může k tomu dojít po přerušení sítě, opakování pokusu nebo ručním opakovaném přehrání. U doručovacích systémů webhooků je běžné doručení alespoň jednou, nikoli právě jednou.

Jako idempotentní klíč použijte ID události. Pokud znovu obdržíte již zpracované ID události a není potřeba žádná další akce, vraťte odpověď 2xx.

Doručení čeká

Ve sloupci HTTP se podívejte na „Další opakování“. Opakovatelné 408, 429, 5xx nebo dočasné síťové selhání zůstává ve stavu Čeká až do dalšího naplánovaného pokusu.

Po uplynutí času opakování klikněte na „Obnovit“ a načtěte nejnovější stav.

Doručení je mrtvé

Všechny automatické pokusy byly vyčerpány. Nejprve opravte přijímač, ujistěte se, že je koncový bod aktivní, odešlete testovací webhook a poté na produkčním doručení použijte funkci Opakovat.

Doporučený produkční kontrolní seznam

Před spoléháním na koncový bod v produkci potvrďte všechny následující body:

1. Přijímač používá stabilní veřejnou URL HTTPS s platným certifikátem.
2. Podpisové tajemství je uloženo mimo zdrojový kód.
3. Podpis se kontroluje proti nezměněnému nezpracovanému tělu.
4. Stará časová razítka jsou odmítána podle zdokumentované tolerance.
5. Přijímač ukládá a deduplikuje ID událostí.
6. Přijímač pro trasování zaznamenává ID událostí a ID doručení.
7. Pomalé zpracování probíhá až po trvalém přijetí události.
8. Odpověď 2xx se vrací pouze u přijatých událostí.
9. Vlastní přihlašovací údaje jsou uloženy v hlavičkách, nikoli v URL.
10. Jsou vybrány pouze požadované typy událostí.
11. Testovací webhook je úspěšný a správně se zobrazuje v historii doručení.
12. Monitorování vás upozorní, když produkční doručení začnou vracet chyby.

S těmito ochrannými opatřeními poskytuje stránka Webhooks obě strany spolehlivé integrace: bezpečné doručování událostí do vaší aplikace a přehlednou provozní historii uvnitř Maildroppy.