Konfigurácia webhookov

Published: 16. júla 2026 · Last updated: 21. júla 2026 · By Marcus Biel

Webhooky umožňujú Maildroppa upozorniť inú aplikáciu, keď sa vo vašom účte stane niečo dôležité.

Namiesto opakovaného zisťovania, či bol odberateľ vytvorený, aktualizovaný, odhlásený alebo označený štítkom, môže vaša aplikácia krátko po udalosti prijať požiadavku HTTPS.

Stránka Webhooks je centrálnym miestom pre túto integráciu platnú pre celý účet. Môžete vytvoriť viacero koncových bodov, vybrať udalosti, ktoré má každý koncový bod prijímať, pridať autentifikačné hlavičky, otestovať pripojenie, skontrolovať pokusy o doručenie a v prípade potreby zopakovať produkčnú udalosť.

Ako fungujú webhooky účtu

Webhook účtu prechádza týmto procesom:

1. V Maildroppe nastane udalosť, napríklad vytvorenie odberateľa.
2. Maildroppa nájde každý aktívny koncový bod prihlásený na odber tejto udalosti.
3. Maildroppa vytvorí jedno doručenie pre každý zodpovedajúci koncový bod.
4. JSON payload podpíše pomocou Signing secret vášho účtu.
5. Maildroppa odošle požiadavku HTTPS POST na uloženú URL koncového bodu.
6. Váš koncový bod overí podpis, uloží alebo spracuje udalosť a vráti HTTP odpoveď.
7. Maildroppa zaznamená výsledok v histórii doručení a dočasné zlyhania automaticky zopakuje.

Ak sa na rovnakú udalosť prihlási viacero koncových bodov, každý koncový bod dostane vlastné doručenie. Obchodná udalosť má pre všetky rovnaké Event ID, zatiaľ čo každé doručenie má vlastné Delivery ID.

Webhooky účtu sa líšia od kroku „Send a webhook“ v automatizácii. Webhooky účtu sledujú vybrané udalosti účtu v celom Maildroppe. Webhook automatizácie sa odošle iba vtedy, keď odberateľ dosiahne konkrétny krok. Obe možnosti používajú Signing secret účtu, takže jeho zmena ovplyvní každý odchádzajúci prijímač webhookov, ktorý overuje podpisy Maildroppy.

Otvorenie stránky Webhooks

Otvorte „Settings“, rozbaľte „Developers“ a vyberte „Webhooks“.

Stránka obsahuje tri hlavné oblasti:

• Signing secret
• Endpoints
• História doručení pre vybraný koncový bod

Ak máte viac než jeden koncový bod, výberom riadku koncového bodu zobrazíte jeho históriu doručení. Ak ste žiadny výslovne nevybrali, Maildroppa zobrazí históriu prvého koncového bodu v zozname.

Pred vytvorením koncového bodu

Pred konfiguráciou Maildroppy pripravte prijímač na svojom serveri. Prijímač by mal:

• Byť dostupný prostredníctvom verejnej URL HTTPS.
• Prijímať požiadavky POST s telom application/json.
• Uchovať pôvodné telo požiadavky, kým sa neoverí podpis Maildroppy.
• Vrátiť stav 2xx až po bezpečnom prijatí udalosti.
• Spracovávať opakované doručenia idempotentne pomocou Event ID.
• Odpovedať rýchlo namiesto vykonávania pomalých operácií počas požiadavky.

Spoľahlivý postup je overiť požiadavku, uložiť Event ID a payload do trvalého frontu alebo databázy, vrátiť 200 alebo 204 a obchodnú operáciu spracovať neskôr.

Nevystavujte vývojový počítač, adresu lokálnej siete ani nechránený skript ako produkčný prijímač webhookov. Maildroppa prijíma iba verejné ciele HTTPS a pri odosielaní doručenia cieľ opäť kontroluje.

Krok 1: Vygenerovanie Signing secret

Každá požiadavka webhooku Maildroppy je podpísaná. Váš prijímač používa Signing secret na overenie, že požiadavku vytvorila Maildroppa a že telo sa počas prenosu nezmenilo.

Panel Signing secret v hornej časti stránky zobrazuje jeden z týchto stavov:

• Missing — Signing secret zatiaľ neexistuje.
• Ready — Signing secret je nakonfigurovaný.
• Loading — Maildroppa načítava aktuálny stav.

Keď je stav Missing, kliknite na „Generate secret“.

Maildroppa nový secret zobrazí okamžite. Začína reťazcom whsec_. Kliknite na „Copy“ a uložte ho do správcu secretov alebo chránenej konfigurácie prostredia, ktorú používa váš prijímač.

Celá hodnota sa zobrazí iba bezprostredne po vygenerovaní alebo zmene. Po opätovnom načítaní alebo opustení stránky Maildroppa zobrazí iba informáciu, že secret existuje, a čas jeho poslednej aktualizácie. Uložený secret už znova nezobrazí.

Ak secret stratíte

Ak prijímač už nemá aktuálny secret, kliknite na „Rotate secret“ a uložte novú zobrazenú hodnotu.

Zmena okamžite nahradí predchádzajúci secret. Maildroppa neuchováva obe hodnoty počas prechodného obdobia. Pred odoslaním ďalších testov alebo spoliehaním sa na produkčné doručenia aktualizujte každý prijímač, ktorý tento účetný secret používa.

Nové doručenia, naplánované opakovania, testy a opakované odoslania sa podpisujú aktuálnym secretom v čase HTTP požiadavky. To znamená, že doručenie vytvorené pred zmenou môže byť pri neskoršom pokuse podpísané novým secretom.

Zaobchádzajte so secretom ako s heslom

Signing secret nevkladajte do kódu v prehliadači, verejného repozitára, URL, chybovej stránky ani bežného aplikačného logu.

Secret potrebuje iba serverový prijímač. Ak sa domnievate, že bol odhalený, okamžite ho zmeňte a aktualizujte všetky prijímače.

Overenie podpisu webhooku

Každá požiadavka obsahuje tieto hlavičky Maildroppy:

• X-Maildroppa-Event-Id — Identifikuje obchodnú udalosť.
• X-Maildroppa-Delivery-Id — Identifikuje konkrétne doručenie.
• X-Maildroppa-Timestamp — Čas podpisu v sekundách Unixu.
• X-Maildroppa-Signature — Verziovaný podpis HMAC.

Maildroppa odosiela aj:

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

Podpis má tento formát:

v1=<lowercase hexadecimal HMAC>

Maildroppa ho vytvára pomocou HMAC-SHA256. Podpísaný obsah tvorí timestamp, za ktorým nasleduje bodka a presné pôvodné telo požiadavky JSON:

<timestamp>.<raw request body>

Ako kľúč HMAC použite Signing secret.

Nasledujúci príklad v Node.js ukazuje základný krok overenia. rawBody musí obsahovať pôvodné bajty požiadavky, nie JSON, ktorý už bol analyzovaný a znova serializovaný.

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 overení podpisu porovnajte timestamp aj s časom svojho servera. Odmietajte požiadavky mimo krátkej tolerancie zvolenej pre vašu infraštruktúru, napríklad päť minút. Znižuje to riziko, že platná zachytená požiadavka bude oveľa neskôr zopakovaná.

JSON analyzujte a spracujte až po úspešnom vykonaní oboch kontrol.

Bežné príčiny chýb podpisu

Podpis zvyčajne zlyhá z jedného z týchto dôvodov:

• Prijímač po zmene používa starý secret.
• Middleware analyzoval alebo zmenil JSON pred výpočtom podpisu.
• Prijímač podpisuje iba telo a vynecháva <timestamp>..
• Timestamp sa interpretuje ako formátovaný dátum namiesto presnej hodnoty hlavičky.
• Pri porovnaní chýba prefix v1=.
• Vypočítaný HMAC je kódovaný inak než malými hexadecimálnymi znakmi.

Pri zlyhaní overenia zaznamenajte Event ID a Delivery ID, nikdy však nezaznamenávajte Signing secret ani citlivé hodnoty vlastných hlavičiek.

Krok 2: Pridanie koncového bodu

V časti Endpoints kliknite na „Add endpoint“.

Editor obsahuje štyri časti:

• Endpoint URL
• Events
• Custom headers
• Active status

Nové koncové body začínajú ako Active a všetky udalosti zobrazené v editore sú na začiatku vybrané. Pred uložením výber skontrolujte, aby prijímač dostával iba upozornenia, ktoré skutočne potrebuje.

Konfigurácia URL koncového bodu

Zadajte úplnú verejnú URL, na ktorú má Maildroppa prijímať požiadavky, napríklad:

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

URL musí spĺňať tieto požiadavky:

• Musí používať https://.
• Musí obsahovať platný verejný hostname.
• Môže mať najviac 2 048 znakov.
• Nesmie obsahovať premenné šablóny s { alebo }.
• Nesmie obsahovať používateľské meno ani heslo pred hostname.
• Nesmie obsahovať fragment URL začínajúci znakom #.
• Musí používať štandardný port HTTPS 443.
• Nesmie používať localhost, nespracovanú IP adresu ani hostname, ktorý sa prekladá na blokovanú súkromnú alebo vyhradenú sieť.

Parametre dotazu sú podporované, do URL však nevkladajte API kľúče ani iné secrety. URL sú viditeľné v zozname koncových bodov a v údajoch o doručení. Na prihlasovacie údaje použite vlastnú hlavičku.

Maildroppa nenasleduje presmerovania. Uložte konečný cieľ HTTPS, nie URL, ktorá vracia 301, 302, 307 alebo 308.

Hostname cieľa sa pred odoslaním znova preloží. Ak sa hostname neskôr preloží na súkromnú alebo blokovanú adresu, bude odmietnutý, aj keď bol pri uložení koncového bodu platný.

Výber udalostí

Vyberte aspoň jednu udalosť. Koncový bod prijíma iba typy udalostí vybrané v jeho editore.

Stránka ponúka tieto možnosti udalostí:

Subscriber Created — subscriber.created

Odosiela sa, keď je v účte Maildroppy vytvorený odberateľ.

Túto udalosť použite na vytvorenie zodpovedajúceho kontaktu v CRM, platforme zákazníckych dát, internej databáze alebo inom systéme rešpektujúcom povolenia.

Nepovažujte túto udalosť za dôkaz, že každá registrácia dokončila Double Opt-in. Stav odberateľa v payloade opisuje jeho aktuálny stav.

Subscriber Updated — subscriber.updated

Odosiela sa, keď sa zmenia vstavané informácie o odberateľovi alebo hodnoty vlastných polí.

Úplný objekt odberateľa v payloade používajte ako aktuálnu reprezentáciu v Maildroppe. Nepredpokladajte, že sa zmenila iba jedna konkrétna vlastnosť.

Priradenia a odstránenia štítkov majú vlastné typy udalostí, aby sa dali spracovať samostatne.

Subscriber Unsubscribed — subscriber.unsubscribed

Odosiela sa, keď odberateľ prejde do stavu unsubscribed prostredníctvom akcie odhlásenia.

Túto udalosť použite na potlačenie kontaktu v prepojených systémoch. Osobu automaticky znova neprihlasujte len preto, že iný systém ju stále označuje ako aktívny kontakt.

Tag Added — subscriber.tag_added

Odosiela sa, keď je odberateľovi priradený štítok.

Payload obsahuje odberateľa a štítok, ktorých sa táto konkrétna zmena týka.

Tag Removed — subscriber.tag_removed

Odosiela sa, keď je odberateľovi odstránený štítok.

Payload obsahuje aktualizovaného odberateľa a odstránený štítok. Odstránený štítok sa poskytuje samostatne, hoci už nie je v aktuálnom poli tags odberateľa.

Form Submitted — form.submitted

Odosiela sa, keď návštevník odošle prihlasovací formulár Maildroppy.

Považujte to za signál odoslania formulára, nie za potvrdenie dokončenia Double Opt-in. Každý pracovný postup vyžadujúci potvrdené prihlásenie musí naďalej rešpektovať aktuálny stav odberateľa a proces potvrdenia.

Používajte samostatné koncové body pri rozdielnych zodpovednostiach

Rôzne udalosti môžete odosielať do rôznych systémov. Napríklad:

• Udalosti odberateľov a štítkov posielajte do CRM.
• Udalosti odhlásenia posielajte službe na potlačenie kontaktov.
• Udalosti odoslania formulára posielajte do analytického kanála.

Samostatné koncové body obmedzujú zbytočnú premávku a uľahčujú diagnostiku zlyhaní. Každý koncový bod má vlastný výber udalostí, URL, vlastné hlavičky, aktívny stav, testy a históriu doručení.

Pridávanie vlastných hlavičiek

Vlastné hlavičky sú voliteľné. Použite ich, keď prijímač vyžaduje API kľúč, bearer token, identifikátor tenanta alebo inú pevnú hlavičku.

Kliknite na „Add header“ a zadajte Header name a Header value. Vhodné príklady:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Môžete pridať najviac 20 vlastných hlavičiek.

Názvy hlavičiek:

• Sú povinné.
• Môžu obsahovať najviac 128 znakov.
• Musia používať platné znaky názvu HTTP hlavičky.
• Musia byť jedinečné bez ohľadu na veľké a malé písmená.

Hodnoty hlavičiek:

• Sú povinné.
• Môžu obsahovať najviac 2 000 znakov.
• Nesmú obsahovať zalomenia riadkov.

Nasledujúce názvy sú vyhradené a nemožno ich nahradiť vlastnou hlavičkou:

• Content-Type
• Content-Length
• Host
• User-Agent
• Akýkoľvek názov začínajúci na X-Maildroppa-

Tým sa zabráni tomu, aby vlastná hodnota nahradila hlavičky doručenia a podpisu Maildroppy.

Ako sa ukladajú secrety hlavičiek

Maildroppa hodnoty vlastných hlavičiek pred uložením šifruje. Uložené hodnoty sa do prehliadača nevracajú v čitateľnej podobe.

Pri neskoršej úprave koncového bodu sa v poli hodnoty zobrazí „Stored value kept“. Ak má existujúci secret zostať nezmenený, ponechajte pole prázdne. Ak ho chcete nahradiť, zadajte novú hodnotu.

Ak zmeníte názov hlavičky, zadajte hodnotu znova. Maildroppa uchová uložený secret iba dovtedy, kým jeho pôvodný názov hlavičky zostane nezmenený.

Odstránením riadku hlavičky sa táto hlavička po uložení koncového bodu odstráni z budúcich doručení.

Hodnoty vlastných hlavičiek sa v uložených informáciách o požiadavke považujú za citlivé. V histórii doručení sú maskované, nie zobrazené.

Nastavenie koncového bodu ako aktívneho alebo neaktívneho

Ak je koncový bod pripravený okamžite prijímať udalosti, ponechajte vybraté „Active“.

Zrušte výber, ak chcete konfiguráciu uložiť bez spustenia doručení. Koncový bod môžete aktivovať neskôr zo zoznamu koncových bodov.

Neaktívny koncový bod:

• Neprijíma novovzniknuté udalosti.
• Nemôže odoslať testovací webhook.
• Zostáva viditeľný a upraviteľný.
• Zachováva svoju existujúcu históriu doručení.

Aktivácia koncového bodu nedoplní udalosti, ktoré nastali počas jeho neaktivity.

Keď sú URL, výber udalostí, hlavičky a stav správne, kliknite na „Save“.

Porozumenie zoznamu koncových bodov

Každý riadok koncového bodu zobrazuje:

• Cieľovú URL.
• Označenie Active alebo Inactive.
• Typy odoberaných udalostí.
• Počet vlastných hlavičiek.
• Čas poslednej aktualizácie koncového bodu.

Dostupné akcie sú:

• On/Off — Aktivuje alebo deaktivuje koncový bod.
• Test — Odošle jednu okamžitú testovaciu požiadavku na aktívny koncový bod.
• Edit — Zmení URL, udalosti, hlavičky alebo aktívny stav.
• Delete — Po potvrdení natrvalo odstráni konfiguráciu koncového bodu.

Výberom hlavnej časti riadku otvoríte históriu doručení daného koncového bodu pod zoznamom.

Ako uložené zmeny ovplyvňujú existujúce doručenia

Udalosť účtu vytvorí doručenie so snímkou URL koncového bodu, payloadu a vlastných hlavičiek platných v danom čase.

Úprava URL alebo vlastných hlavičiek ovplyvní novovytvorené doručenia. Doručenie, ktoré už bolo zaradené do frontu, si ponechá pôvodný cieľ a uloženú konfiguráciu hlavičiek.

Zmena vybraných udalostí ovplyvní iba udalosti, ktoré nastanú neskôr. Maildroppa nevytvára doručenia spätne pre typy udalostí, ktoré neboli vybrané v čase vzniku udalosti.

Signing secret je odlišný: načíta sa pri príprave HTTP požiadavky. Čakajúce doručenie alebo opakované odoslanie preto môže použiť novo zmenený Signing secret, aj keď jeho payload a snímka koncového bodu vznikli skôr.

Testovanie koncového bodu

Po pripravení prijímača a Signing secret kliknite na „Test“ pri aktívnom koncovom bode.

Maildroppa okamžite odošle jednu podpísanú požiadavku s použitím uloženej URL koncového bodu a uložených vlastných hlavičiek. Neuložené zmeny v otvorenom editore nie sú súčasťou testu.

Testovací payload používa typ udalosti 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 timestamp sa pri každom skutočnom teste líšia.

Test vykoná presne jeden pokus HTTP. Testovacie doručenia nie sú zaradené do produkčného plánu opakovaní a nemožno ich zopakovať.

Po dokončení požiadavky panel výsledku zobrazí:

• Test success alebo Test failed
• Event ID
• HTTP status, ak bola prijatá odpoveď
• Trvanie
• Delivery ID
• Informácie o chybe, ak sú k dispozícii
• Úryvok odpovede, ak prijímač vrátil telo

Test sa zobrazí aj v histórii doručení s označením Test. Filter „Test“ použite na zobrazenie iba testovacích požiadaviek.

Porozumenie produkčnému payloadu

Produkčné udalosti účtu používajú spoločný obal JSON:

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

Vlastnosti najvyššej úrovne znamenajú:

• id — Event ID. Zhoduje sa s X-Maildroppa-Event-Id.
• type — Kľúč udalosti vybraný v editore koncového bodu.
• schema_version — Verzia schémy payloadu. Použite ju pri rozhodovaní, ako udalosť analyzovať.
• created_at — Čas vytvorenia payloadu udalosti v UTC.
• livemode — true pre produkčné udalosti a false pre testovacie udalosti.
• data — Obsah špecifický pre udalosť.

Udalosti smerujte podľa presnej hodnoty type. Ďalšie vlastnosti, ktoré vaša integrácia nepotrebuje, ignorujte, aby kompatibilné rozšírenia payloadu neporušili prijímač.

Payload udalosti odberateľa

Udalosti odberateľa obsahujú aktuálnu reprezentáciu odberateľa v 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 sú polia. Môžu byť prázdne. Vlastnosť odberateľa môže byť aj null, keď neexistuje žiadna hodnota, preto by sa váš prijímač mal riadiť schémou payloadu a nemal predpokladať, že každá voliteľná profilová hodnota je prítomná.

Payload udalosti štítku

Udalosti štítkov obsahujú odberateľa aj štítok, ktorý udalosť vyvolal:

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

Pri subscriber.tag_removed údaj data.tag stále identifikuje odstránený štítok, hoci aktuálne pole tags odberateľa ho už neobsahuje.

Event ID, Delivery ID a idempotencia

Event ID a Delivery ID slúžia na odlišné účely.

Event ID

Event ID identifikuje obchodnú udalosť. Objavuje sa v:

• Vlastnosti id na najvyššej úrovni payloadu.
• Hlavičke požiadavky X-Maildroppa-Event-Id.
• Histórii doručení.

Rovnaká udalosť môže byť odoslaná viacerým prihláseným koncovým bodom. Tieto doručenia zdieľajú Event ID.

Opakovania a manuálne opakované odoslania si tiež zachovávajú pôvodné Event ID. Ukladajte spracované Event ID a obchodnú operáciu vytvorte idempotentne, aby opakovaná požiadavka nevytvorila duplicitné kontakty, neopakovala nevratnú operáciu ani neuplatnila rovnakú zmenu dvakrát.

Delivery ID

Delivery ID identifikuje jeden záznam doručenia. Objavuje sa v:

• Hlavičke požiadavky X-Maildroppa-Delivery-Id.
• Histórii doručení.

Každé doručenie koncovému bodu má vlastné Delivery ID. Manuálne opakované odoslanie vytvorí nové Delivery ID, pričom zachová pôvodné Event ID.

Delivery ID používajte na technické sledovanie a podporu. Event ID používajte na deduplikáciu na obchodnej úrovni.

Vrátenie správnej HTTP odpovede

Maildroppa klasifikuje odpovede takto:

• Každá odpoveď 2xx označí doručenie ako úspešné.
• Odpovede 408 Request Timeout, 429 Too Many Requests a 5xx sú dočasné zlyhania a možno ich zopakovať.
• Sieťové zlyhania, ktoré môžu byť dočasné, sa opakujú.
• Presmerovania a iné odpovede 3xx sa nenasledujú a považujú sa za konečné zlyhania.
• Ostatné odpovede 4xx sa považujú za konečné zlyhania a neopakujú sa.

200, 202 alebo 204 vráťte iba vtedy, keď bola udalosť bezpečne prijatá. Ak spracovanie trvá, najprv udalosť uložte a vráťte úspešnú odpoveď, potom pomalšiu prácu vykonajte asynchrónne.

Nevracajte presmerovanie na inú URL webhooku. Namiesto toho nakonfigurujte konečnú URL v Maildroppe.

Automatický plán opakovaní

Produkčné doručenia môžu vykonať až sedem pokusov HTTP.

Po zlyhaní, ktoré možno zopakovať, Maildroppa naplánuje ďalší pokus s týmito oneskoreniami:

1. Po pokuse 1: 1 minúta
2. Po pokuse 2: 5 minút
3. Po pokuse 3: 30 minút
4. Po pokuse 4: 2 hodiny
5. Po pokuse 5: 12 hodín
6. Po pokuse 6: 24 hodín

Ak pokus 7 stále skončí zlyhaním, ktoré možno zopakovať, doručenie prejde do stavu Dead a ďalší automatický pokus sa nenaplánuje.

Plán sa meria od jednotlivých neúspešných pokusov. Skutočný čas doručenia môže byť o niečo neskorší, pretože doručenia sa spracúvajú asynchrónne a podliehajú aj ochranným limitom systému.

Ak je to možné, do zobrazeného času „Next retry“ opravte dočasný problém prijímača. Ak sa automatické pokusy skončili, po opätovnom sprevádzkovaní prijímača použite Replay.

Porozumenie histórii doručení

História doručení patrí aktuálne vybranému koncovému bodu. V hlavičke sekcie sa zobrazuje URL koncového bodu, aby ste si mohli overiť, ktorú históriu sledujete.

Použite tieto filtre:

• All — Zobrazuje produkčné aj testovacie doručenia.
• Production — Zobrazuje iba doručenia živých udalostí.
• Test — Zobrazuje iba manuálne testy.

Kliknutím na „Refresh“ načítate najnovší stav. História nemusí zostať otvorená, kým Maildroppa odosiela alebo opakuje doručenie.

Stránka zobrazuje najnovších 50 doručení zodpovedajúcich vybranému filtru.

Stĺpce doručenia

Každý riadok obsahuje:

• Created — Kedy bol záznam doručenia vytvorený.
• State — Pending, Success, Failed alebo Dead.
• HTTP — Stav odpovede, počet pokusov, trvanie a čas ďalšieho opakovania, ak je relevantný.
• Subscriber — E-mail odberateľa, ak je udalosť spojená s odberateľom.
• Delivery — Typ udalosti, Event ID a Delivery ID.
• Actions — Replay, ak je doručenie oprávnené na opakovanie.

Ak sa nevykonal žiadny pokus HTTP, stĺpec HTTP zobrazuje „No HTTP attempt“. Môže sa to stať, keď Maildroppa požiadavku odmietne ešte pred odoslaním, napríklad preto, že chýba Signing secret alebo uložený cieľ už nemožno bezpečne použiť.

Ak sú dostupné, riadok zobrazuje aj Error a Response excerpt vrátené prijímačom. Do tela odpovede webhooku nevracajte secrety ani citlivé osobné údaje, pretože časť tejto odpovede sa môže zobraziť v denníku doručení účtu.

Stavy doručenia

Pending znamená, že doručenie čaká na prvý pokus alebo naplánované opakovanie. „Next retry“ sa zobrazí, keď bol naplánovaný ďalší pokus.

Success znamená, že prijímač vrátil odpoveď 2xx. Ďalší automatický pokus nie je potrebný.

Failed znamená, že doručenie skončilo neopakovateľným problémom, bolo odmietnuté pred pokusom HTTP alebo zastavené pred odoslaním.

Dead znamená, že sa využili všetky automatické pokusy pri probléme, ktorý možno zopakovať, bez prijatia úspešnej odpovede.

Uchovávanie histórie

Záznamy doručení sa uchovávajú obmedzený čas:

• Úspešné produkčné doručenia: 30 dní
• Neúspešné produkčné doručenia: 90 dní
• Produkčné doručenia Dead: 90 dní
• Testovacie doručenia: 30 dní

Ak potrebujete dlhšiu auditnú históriu, uchovávajte vlastné integračné logy. Ukladajte Event ID a Delivery ID, ale zbytočne neukladajte secrety.

Opakovanie doručenia

Kliknite na „Replay“, keď sa má dokončené produkčné doručenie skúsiť znova.

Replay je dostupné pre produkčné doručenia v stave Success, Failed alebo Dead. Nie je dostupné, keď je doručenie Pending, a testovacie doručenia nemožno opakovať.

Opakované odoslanie:

• Vytvorí nové doručenie Pending.
• Vytvorí nové Delivery ID.
• Zachová pôvodné Event ID.
• Zachová pôvodný typ udalosti a payload JSON.
• Použije pôvodnú uloženú cieľovú URL a snímku vlastných hlavičiek.
• Pri príprave novej požiadavky použije aktuálny Signing secret.

Replay znovu nevytvára payload z aktuálnych údajov odberateľa. Znova odošle pôvodnú snímku udalosti. Vďaka tomu je opakované odoslanie auditovateľné a historická udalosť nemôže potichu zmeniť význam.

Naraz môže byť Pending iba jedno opakované odoslanie toho istého zdrojového doručenia. Pred vyžiadaním ďalšieho počkajte, kým sa toto opakované odoslanie dokončí.

Pred opakovaným odoslaním skontrolujte, či je koncový bod Active. Ak je neaktívny, zaradené opakované odoslanie nemožno úspešne doručiť.

Keďže prijímač mohol obchodnú operáciu dokončiť aj vtedy, keď Maildroppa nedostala jeho úspešnú odpoveď, opakované odoslanie môže vytvoriť duplicitnú požiadavku. Deduplikácia podľa Event ID chráni prepojený systém pred opakovaním operácie.

Úprava koncového bodu

Kliknutím na „Edit“ zmeníte URL, výber udalostí, vlastné hlavičky alebo aktívny stav.

Pred uložením:

1. Overte, že nová URL je už dostupná.
2. Ak majú zostať nezmenené, ponechajte uložené hodnoty hlavičiek prázdne.
3. Pri každej premenovanej hlavičke zadajte novú hodnotu.
4. Skontrolujte výber udalostí, aby sa omylom neodstránili potrebné upozornenia.
5. Uložte zmeny a odošlite nový testovací webhook.

Pamätajte, že doručenia zaradené vo fronte si zachovávajú existujúcu URL a snímku vlastných hlavičiek. Novú konfiguráciu testujte pre budúce doručenia a nepredpokladajte, že zmení staršiu požiadavku vo fronte.

Deaktivácia koncového bodu

Použite prepínač On/Off, keď chcete integráciu pozastaviť bez odstránenia jej konfigurácie a histórie.

Keď je koncový bod prepnutý na Off:

• Nové udalosti sa preň už nezaraďujú do frontu.
• Pending doručenia, ktoré ešte neboli prevzaté na odoslanie, sa označia ako Failed.
• Test je deaktivovaný.
• Koncový bod zostáva dostupný na úpravu a neskoršiu aktiváciu.

Požiadavka, ktorá prebiehala v momente deaktivácie, môže byť stále dokončená. Ak je toto rozlíšenie pre vašu integráciu dôležité, po vypnutí koncového bodu skontrolujte históriu doručení.

Udalosti zmeškané počas neaktivity koncového bodu sa po jeho opätovnom zapnutí nedoplnia.

Odstránenie koncového bodu

Keď koncový bod už nemá existovať, kliknite na „Delete“ a potvrďte varovanie.

Odstránením sa koncový bod odstráni zo stránky, zastavia sa budúce doručenia udalostí a Pending doručenia, ktoré ešte neboli prevzaté na odoslanie, sa označia ako Failed.

Delete nie je spôsob dočasného pozastavenia. Ak konfiguráciu alebo jej viditeľnú históriu možno budete znova potrebovať, použite prepínač On/Off.

Pred odstránením si zaznamenajte všetky Event ID alebo Delivery ID, ktoré ešte potrebujete na audit integrácie.

Riešenie problémov

Koncový bod nemožno uložiť

Skontrolujte, či:

• URL začína na https://.
• URL používa verejný hostname a port 443.
• URL neobsahuje premenné, prihlasovacie údaje ani fragment.
• Je vybraná aspoň jedna udalosť.
• Každá vlastná hlavička má jedinečný názov a hodnotu.
• Ako vlastné názvy sa nepoužívajú vyhradené hlavičky Maildroppy a HTTP.

Test je deaktivovaný

Test je dostupný iba pre aktívny koncový bod. Zapnite koncový bod alebo ho upravte a vyberte „Active“, potom pred testovaním uložte zmeny.

Test nezobrazuje žiadny pokus HTTP

Ak je stav Missing, vygenerujte Signing secret. Skontrolujte tiež, či je hostname cieľa verejný a stále sa správne prekladá.

Požiadavka môže byť odmietnutá pred odoslaním, ak je jej secret, URL, vlastná hlavička alebo bezpečnostná kontrola cieľa neplatná.

Prijímač vracia 401 alebo 403

Skontrolujte uložený názov vlastnej hlavičky a prihlasovací údaj. Ak sa zmenil, upravte koncový bod a zadajte hodnotu znova.

Overte tiež, či prijímač nezamieňa vlastný API prihlasovací údaj s podpisom Maildroppy. Vlastná autorizačná hlavička a X-Maildroppa-Signature slúžia na odlišné účely a možno ich kontrolovať nezávisle.

Prijímač vracia presmerovanie

Maildroppa nenasleduje presmerovania. Nahraďte URL koncového bodu konečnou verejnou URL HTTPS a test zopakujte.

Podpis sa nezhoduje

Overte, či prijímač:

• Používa aktuálny Signing secret.
• Používa presnú hodnotu X-Maildroppa-Timestamp.
• Podpisuje <timestamp>.<raw request body>.
• Používa HMAC-SHA256 a výstup v malých hexadecimálnych znakoch.
• Porovnáva celú hodnotu vrátane v1=.
• Vykonáva porovnanie pred tým, ako analýza JSON zmení telo.

Rovnaká udalosť prichádza viackrát

Môže sa to stať po prerušení siete, opakovaní alebo manuálnom opakovanom odoslaní. Je bežné, že systémy doručovania webhookov poskytujú doručenie aspoň raz, nie presne raz.

Event ID používajte ako idempotency key. Keď znova prijmete už spracované Event ID a nie je potrebná ďalšia akcia, vráťte odpoveď 2xx.

Doručenie je Pending

V stĺpci HTTP skontrolujte „Next retry“. Opakovateľné 408, 429, 5xx alebo dočasné sieťové zlyhanie zostáva Pending až do ďalšieho naplánovaného pokusu.

Po čase opakovania kliknite na „Refresh“, aby ste načítali najnovší stav.

Doručenie je Dead

Všetky automatické pokusy boli využité. Najprv opravte prijímač, uistite sa, že koncový bod je Active, odošlite testovací webhook a potom použite Replay pri produkčnom doručení.

Odporúčaný produkčný kontrolný zoznam

Pred spoliehaním sa na koncový bod v produkcii potvrďte všetky nasledujúce body:

1. Prijímač používa stabilnú verejnú URL HTTPS s platným certifikátom.
2. Signing secret je uložený mimo zdrojového kódu.
3. Podpis sa kontroluje voči nezmenenému pôvodnému telu.
4. Staré timestampy sa odmietajú podľa zdokumentovanej tolerancie.
5. Prijímač ukladá a deduplikuje Event ID.
6. Prijímač zaznamenáva Event ID a Delivery ID na sledovanie.
7. Pomalé spracovanie prebieha až po trvalom prijatí udalosti.
8. Odpoveď 2xx sa vracia iba pri prijatých udalostiach.
9. Vlastné prihlasovacie údaje sa ukladajú do hlavičiek, nie do URL.
10. Sú vybrané iba potrebné typy udalostí.
11. Testovací webhook je úspešný a správne sa zobrazuje v histórii doručení.
12. Monitorovanie vás upozorní, keď produkčné doručenia začnú vracať chyby.

S týmito ochrannými opatreniami poskytuje stránka Webhooks obe strany spoľahlivej integrácie: bezpečné doručovanie udalostí do vašej aplikácie a jasnú prevádzkovú históriu v Maildroppe.