Seadista Webhookid

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

Webhookid võimaldavad Maildroppal teavitada teist rakendust, kui sinu kontol toimub midagi olulist.

Selle asemel et korduvalt küsida Maildroppalt, kas tellija loodi, seda uuendati, tellimus tühistati või talle määrati silt, saab sinu rakendus varsti pärast sündmuse toimumist vastu võtta HTTPS-päringu.

Webhookide leht on selle kontot hõlmava integratsiooni keskne koht. Saad luua mitu lõpp-punkti, valida sündmused, mida iga lõpp-punkt vastu võtab, lisada autentimispäiseid, ühendust testida, edastuskatseid uurida ja vajaduse korral tootmissündmuse uuesti edastada.

Kuidas konto webhookid töötavad

Konto webhook järgib järgmist protsessi:

1. Maildroppas toimub sündmus, näiteks tellija loomine.
2. Maildroppa leiab kõik aktiivsed lõpp-punktid, mis on selle sündmuse tellinud.
3. Maildroppa loob iga sobiva lõpp-punkti jaoks ühe edastuse.
4. JSON-i kasulik koormus allkirjastatakse sinu konto webhooki allkirjastamisvõtmega.
5. Maildroppa saadab salvestatud lõpp-punkti URL-ile HTTPS-i POST-päringu.
6. Sinu lõpp-punkt kontrollib allkirja, salvestab või töötleb sündmuse ja tagastab HTTP-vastuse.
7. Maildroppa salvestab tulemuse edastusajalukku ja proovib ajutiste tõrgete korral automaatselt uuesti.

Kui sama sündmuse on tellinud mitu lõpp-punkti, saab iga lõpp-punkt oma edastuse. Äriprotsessi sündmusel on kõigi nende puhul sama sündmuse ID, kuid igal edastusel on oma edastuse ID.

Konto webhookid erinevad automaatika sees olevast sammust „Saada webhook”. Konto webhookid kuulavad Maildroppas valitud konto sündmusi. Automaatika webhook saadetakse ainult siis, kui tellija jõuab selle konkreetse sammuni. Mõlemad kasutavad konto webhooki allkirjastamisvõtit, seega mõjutab võtme vahetamine kõiki väljaminevaid webhooki vastuvõtjaid, kes Maildroppa allkirju kontrollivad.

Webhookide lehe avamine

Ava „Settings”, laienda „Developers” ja vali „Webhooks”.

Lehel on kolm põhiala:

• allkirjastamisvõti
• lõpp-punktid
• valitud lõpp-punkti edastuste ajalugu

Kui sul on rohkem kui üks lõpp-punkt, vali selle edastusajaloo kuvamiseks lõpp-punkti rida. Kui sa pole ühtegi lõpp-punkti sõnaselgelt valinud, kuvab Maildroppa loendi esimese lõpp-punkti ajaloo.

Enne lõpp-punkti loomist

Valmista oma serveris vastuvõtja ette enne Maildroppa seadistamist. Vastuvõtja peaks:

• olema kättesaadav avaliku HTTPS-i URL-i kaudu;
• vastu võtma POST-päringuid kehaga application/json;
• säilitama päringu töötlemata keha, kuni Maildroppa allkiri on kontrollitud;
• tagastama 2xx-olekukoodi alles pärast sündmuse turvalist vastuvõtmist;
• töötlema korduvaid edastusi idempotentselt, kasutades sündmuse ID-d;
• vastama kiiresti, mitte tehes päringu ajal aeglast tööd.

Usaldusväärne lahendus on päring kontrollida, salvestada sündmuse ID ja kasulik koormus püsivasse järjekorda või andmebaasi, tagastada 200 või 204 ning töödelda ärilist tegevust hiljem.

Ära avalda arendusarvutit, kohaliku võrgu aadressi ega kaitsmata skripti tootmise webhooki vastuvõtjana. Maildroppa aktsepteerib ainult avalikke HTTPS-sihtkohti ja kontrollib sihtkohta uuesti, kui edastus saadetakse.

1. samm: allkirjastamisvõtme genereerimine

---

Iga Maildroppa webhooki päring on allkirjastatud. Sinu vastuvõtja kasutab allkirjastamisvõtit, et kontrollida, kas päringu lõi Maildroppa ja kas keha ei muutunud edastuse ajal.

Lehe ülaosas näitab allkirjastamisvõtme paneel üht järgmistest olekutest:

• Puudub — allkirjastamisvõtit pole veel olemas.
• Valmis — allkirjastamisvõti on seadistatud.
• Laadimine — Maildroppa hangib praegust olekut.

Kui olek on „Puudub”, klõpsa „Generate secret”.

Maildroppa kuvab uue võtme kohe. See algab väärtusega whsec_. Klõpsa „Copy” ja salvesta see oma vastuvõtja kasutatavasse saladuste haldurisse või kaitstud keskkonnakonfiguratsiooni.

Täielikku väärtust kuvatakse ainult kohe pärast genereerimist või vahetamist. Lehe uuesti laadimisel või sellelt lahkumisel näitab Maildroppa ainult seda, et võti on olemas, ja millal seda viimati uuendati. Salvestatud võtit uuesti ei kuvata.

Kui kaotad võtme

Kui vastuvõtjal pole enam praegust võtit, klõpsa „Rotate secret” ja salvesta äsja kuvatud väärtus.

Vahetamine asendab eelmise võtme kohe. Maildroppa ei säilita üleminekuperioodil mõlemat väärtust. Uuenda enne uute testide saatmist või tootmisedastustele tuginemist kõiki vastuvõtjaid, kes seda konto võtit kasutavad.

Uued edastused, ajastatud korduskatsed, testid ja uuestiedastused allkirjastatakse HTTP-päringu tegemise hetkel kehtiva võtmega. See tähendab, et enne võtme vahetamist loodud edastus võidakse hiljem proovimisel allkirjastada juba uue võtmega.

Käsitle võtit nagu parooli

Ära paiguta allkirjastamisvõtit brauserikoodi, avalikku hoidlasse, URL-i, vealehele ega tavalisse rakenduse logisse.

Võtit vajab ainult serveripoolne vastuvõtja. Kui arvad, et võti on avalikuks saanud, vaheta see ja uuenda kohe kõiki vastuvõtjaid.

Webhooki allkirja kontrollimine

Iga päring sisaldab järgmisi Maildroppa päiseid:

• X-Maildroppa-Event-Id — tuvastab ärilise sündmuse.
• X-Maildroppa-Delivery-Id — tuvastab konkreetse edastuse.
• X-Maildroppa-Timestamp — allkirjastamise aeg Unixi sekundites.
• X-Maildroppa-Signature — versiooniga HMAC-allkiri.

Maildroppa saadab ka järgmised päised:

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

Allkiri on järgmises vormingus:

v1=<lowercase hexadecimal HMAC>

Maildroppa loob selle HMAC-SHA256 abil. Allkirjastatud sisu koosneb ajatemplist, punktist ja täpsest töötlemata JSON-päringu kehast:

<timestamp>.<raw request body>

Kasuta HMAC-võtmena allkirjastamisvõtit.

Järgnev Node.js-i näide näitab olulist kontrollietappi. rawBody peab olema algse päringu baidid, mitte JSON, mis on juba parsitud ja uuesti serialiseeritud.

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);
}

Pärast allkirja kontrollimist võrdle ka ajatemplit oma serveri ajaga. Lükka tagasi päringud, mis jäävad sinu taristu jaoks valitud lühikesest lubatud ajavahemikust väljapoole, näiteks viiest minutist. See vähendab ohtu, et kinni püütud kehtiv päring hiljem uuesti esitatakse.

Parsii ja töötle JSON-i alles pärast mõlema kontrolli läbimist.

Allkirjavigade levinud põhjused

Allkiri ebaõnnestub tavaliselt ühel järgmistest põhjustest:

• vastuvõtja kasutab pärast võtme vahetamist vana võtit;
• vahevara parsis või muutis JSON-i enne allkirja arvutamist;
• vastuvõtja allkirjastab ainult keha ja jätab <timestamp>. välja;
• ajatemplit käsitletakse vormindatud kuupäevana, mitte päise täpse väärtusena;
• võrdlusest jäetakse v1= eesliide välja;
• arvutatud HMAC kodeeritakse teisiti kui väiketähtedega kuueteistkümnendsüsteemis.

Logi kontrolli ebaõnnestumisel sündmuse ID ja edastuse ID, kuid ära kunagi logi allkirjastamisvõtit ega tundlike kohandatud päiste väärtusi.

2. samm: lõpp-punkti lisamine

---

Klõpsa lõpp-punktide jaotises „Add endpoint”.

Redaktor koosneb neljast osast:

• lõpp-punkti URL
• sündmused
• kohandatud päised
• aktiivne olek

Uued lõpp-punktid on vaikimisi aktiivsed ja kõik redaktoris kuvatud sündmused on algselt valitud. Vaata valik enne salvestamist üle, et vastuvõtja saaks ainult need teavitused, mida tal tegelikult vaja on.

Lõpp-punkti URL-i seadistamine

Sisesta täielik avalik URL, mis peaks Maildroppa päringuid vastu võtma, näiteks:

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

URL peab vastama järgmistele nõuetele:

• see peab kasutama https://-i;
• see peab sisaldama kehtivat avalikku hostinime;
• see võib olla kuni 2048 märki pikk;
• see ei tohi sisaldada mallimuutujaid märkidega { või };
• see ei tohi sisaldada kasutajanime ega parooli enne hostinime;
• see ei tohi sisaldada märgiga # algavat URL-i fragmenti;
• see peab kasutama HTTPS-i standardporti 443;
• see ei tohi kasutada localhost-i, töötlemata IP-aadressi ega hostinime, mis lahendub blokeeritud privaat- või reserveeritud võrku.

Päringuparameetreid toetatakse, kuid ära paiguta URL-i API-võtmeid ega muid saladusi. URL-id on nähtavad lõpp-punktide loendis ja edastusandmetes. Kasuta mandaatide jaoks selle asemel kohandatud päist.

Maildroppa ei järgi ümbersuunamisi. Salvesta lõplik HTTPS-sihtkoht, mitte URL, mis tagastab 301, 302, 307 või 308.

Sihtkoha hostinimi lahendatakse enne saatmist uuesti. Hostinimi, mis lahendub hiljem privaatseks või blokeeritud aadressiks, lükatakse tagasi isegi siis, kui see oli lõpp-punkti salvestamisel kehtiv.

Sündmuste valimine

Vali vähemalt üks sündmus. Lõpp-punkt saab ainult need sündmustüübid, mis on tema redaktoris valitud.

Lehel on järgmised sündmuste valikud:

Tellija loodud — subscriber.created

Saadetakse siis, kui Maildroppa kontol luuakse tellija.

Kasuta seda sündmust vastava kontakti loomiseks CRM-is, kliendiandmeplatvormil, sisemises andmebaasis või muus õigusi arvestavas süsteemis.

Ära tõlgenda seda sündmust tõendina, et iga registreerumine on läbinud topeltkinnituse. Kasulikus koormuses olev tellija olek kirjeldab praegust seisundit.

Tellija uuendatud — subscriber.updated

Saadetakse siis, kui tellija sisseehitatud teave või kohandatud väljade väärtused muutuvad.

Kasuta kasulikus koormuses olevat täielikku tellijaobjekti Maildroppa praeguse esitlusena. Ära eelda, et muutus toimus ainult ühes konkreetses atribuudis.

Siltide määramisel ja eemaldamisel on oma sündmustüübid, et neid saaks eraldi käsitleda.

Tellija loobus — subscriber.unsubscribed

Saadetakse siis, kui tellija liigub loobunud olekusse loobumistoimingu kaudu.

Kasuta seda sündmust kontakti vaigistamiseks ühendatud süsteemides. Ära telli inimest automaatselt uuesti, sest mõni teine süsteem märgib kontakti endiselt aktiivseks.

Silt lisatud — subscriber.tag_added

Saadetakse siis, kui tellijale määratakse silt.

Kasulik koormus sisaldab selle konkreetse muudatusega seotud tellijat ja silti.

Silt eemaldatud — subscriber.tag_removed

Saadetakse siis, kui tellijalt eemaldatakse silt.

Kasulik koormus sisaldab uuendatud tellijat ja eemaldatud silti. Eemaldatud silt antakse eraldi, kuigi seda tellija praeguses tags-massiivis enam pole.

Vorm saadetud — form.submitted

Saadetakse siis, kui külastaja saadab Maildroppa registreerumisvormi.

Käsitle seda vormi saatmise signaalina, mitte kinnitusena, et topeltkinnitus on lõpetatud. Iga töövoog, mis nõuab kinnitatud tellimust, peab jätkuvalt arvestama tellija praeguse oleku ja kinnitusprotsessiga.

Kasuta erinevate vastutusalade jaoks eraldi lõpp-punkte

Saad saata erinevad sündmused erinevatele süsteemidele. Näiteks:

• saada tellija- ja sildisündmused CRM-i;
• saada loobumissündmused vaigistamisteenusele;
• saada vormi saatmise sündmused analüütikatorusse.

Eraldi lõpp-punktid vähendavad tarbetut liiklust ja muudavad tõrgete diagnoosimise lihtsamaks. Igal lõpp-punktil on oma sündmuste valik, URL, kohandatud päised, aktiivne olek, testid ja edastuste ajalugu.

Kohandatud päiste lisamine

Kohandatud päised on valikulised. Kasuta neid, kui vastuvõtja vajab API-võtit, kandjaluba, rentniku identifikaatorit või muud püsivat päist.

Klõpsa „Add header” ja sisesta päise nimi ning päise väärtus. Sobivad näited on:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Saad lisada kuni 20 kohandatud päist.

Päiste nimed:

• on nõutud;
• võivad sisaldada kuni 128 märki;
• peavad kasutama kehtivaid HTTP päise nime märke;
• peavad suur- ja väiketähtedest sõltumata olema kordumatud.

Päiste väärtused:

• on nõutud;
• võivad sisaldada kuni 2000 märki;
• ei tohi sisaldada reavahetusi.

Järgmised nimed on reserveeritud ja neid ei saa kohandatud päisega asendada:

• Content-Type
• Content-Length
• Host
• User-Agent
• kõik nimed, mis algavad väärtusega X-Maildroppa-

See takistab kohandatud väärtusel Maildroppa edastus- ja allkirjapäiseid asendada.

Kuidas päiste saladusi salvestatakse

Maildroppa krüpteerib kohandatud päiste väärtused enne nende salvestamist. Salvestatud väärtusi ei tagastata brauserisse loetaval kujul.

Kui muudad lõpp-punkti hiljem, kuvab väärtuseväli teksti „Stored value kept”. Jäta see tühjaks, kui olemasolev saladus peab jääma muutmata. Sisesta uus väärtus selle asendamiseks.

Kui muudad päise nime, sisesta väärtus uuesti. Maildroppa säilitab salvestatud saladuse ainult seni, kuni algne päise nimi jääb samaks.

Päise rea eemaldamine eemaldab selle päise tulevastest edastustest pärast lõpp-punkti salvestamist.

Kohandatud päiste väärtusi käsitletakse salvestatud päringuteabes tundlikena. Edastusajaloos kuvatakse need varjatult, mitte täielikult.

Lõpp-punkti aktiivseks või mitteaktiivseks määramine

Jäta „Active” valituks, kui lõpp-punkt on valmis kohe sündmusi vastu võtma.

Tühista valik, kui soovid konfiguratsiooni salvestada ilma edastusi alustamata. Saad lõpp-punkti hiljem lõpp-punktide loendis aktiveerida.

Mitteaktiivne lõpp-punkt:

• ei saa uusi sündmusi;
• ei saa saata test-webhooki;
• jääb nähtavaks ja muudetavaks;
• säilitab olemasoleva edastusajaloo.

Lõpp-punkti aktiveerimine ei täida tagantjärele sündmusi, mis toimusid selle mitteaktiivsuse ajal.

Klõpsa „Save”, kui URL, sündmuste valik, päised ja olek on õiged.

Lõpp-punktide loendi mõistmine

Igal lõpp-punkti real kuvatakse:

• sihtkoha URL;
• aktiivse või mitteaktiivse oleku märk;
• tellitud sündmustüübid;
• kohandatud päiste arv;
• lõpp-punkti viimase uuendamise aeg.

Saadaval on järgmised toimingud:

• On/Off — aktiveerib või deaktiveerib lõpp-punkti;
• Test — saadab aktiivsele lõpp-punktile ühe kohese testpäringu;
• Edit — muudab URL-i, sündmusi, päiseid või aktiivset olekut;
• Delete — eemaldab pärast kinnitamist lõplikult lõpp-punkti konfiguratsiooni.

Vali rea põhiosa, et avada loendi all selle lõpp-punkti edastuste ajalugu.

Kuidas salvestatud muudatused mõjutavad olemasolevaid edastusi

Konto sündmus loob edastuse, mis sisaldab sel hetkel lõpp-punkti URL-i, kasuliku koormuse ja kohandatud päiste hetktõmmist.

URL-i või kohandatud päiste muutmine mõjutab uusi loodavaid edastusi. Juba järjekorda pandud edastus säilitab algse sihtkoha ja salvestatud päiste konfiguratsiooni.

Valitud sündmuste muutmine mõjutab samuti ainult hiljem toimuvaid sündmusi. Maildroppa ei loo tagantjärele edastusi sündmustüüpidele, mida sündmuse toimumise ajal ei valitud.

Allkirjastamisvõti on erinev: seda loetakse HTTP-päringu ettevalmistamisel. Seetõttu võib ootel edastus või uuestiedastus kasutada äsja vahetatud allkirjastamisvõtit isegi siis, kui selle kasulik koormus ja lõpp-punkti hetktõmmis loodi varem.

Lõpp-punkti testimine

Klõpsa aktiivsel lõpp-punktil „Test”, kui vastuvõtja ja allkirjastamisvõti on valmis.

Maildroppa saadab kohe ühe allkirjastatud päringu, kasutades salvestatud lõpp-punkti URL-i ja kohandatud päiseid. Avatud redaktoris salvestamata muudatused testi ei kuulu.

Testi kasulik koormus kasutab sündmustüüpi webhook.test ja määrab livemode väärtuseks 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."
  }
}

Genereeritud ID-d ja ajatempel erinevad iga tegeliku testi puhul.

Test teeb täpselt ühe HTTP-katse. Testedastusi ei lisata tootmise korduskatsete ajakavasse ja neid ei saa uuesti edastada.

Pärast päringu lõppu kuvab tulemuste paneel:

• testi õnnestumise või ebaõnnestumise;
• sündmuse ID;
• HTTP-olekukoodi, kui vastus saadi;
• kestuse;
• edastuse ID;
• veateabe, kui see on saadaval;
• vastuse väljavõtte, kui vastuvõtja tagastas keha.

Test kuvatakse ka edastusajaloos testi märgisega. Ainult testpäringute kuvamiseks kasuta filtrit „Test”.

Tootmise kasuliku koormuse mõistmine

Tootmise kontosündmused kasutavad ühist JSON-ümbrist:

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

Ülataseme atribuudid tähendavad järgmist:

• id — sündmuse ID. See vastab väärtusele X-Maildroppa-Event-Id.
• type — lõpp-punkti redaktoris valitud sündmuse võti.
• schema_version — kasuliku koormuse skeemi versioon. Kasuta seda sündmuse parsimise otsustamisel.
• created_at — kasuliku koormuse loomise aeg UTC-s.
• livemode — tootmissündmuste puhul true ja testsündmuste puhul false.
• data — sündmusepõhine sisu.

Suunake sündmused täpse type-väärtuse järgi. Eira lisaatribuute, mida integratsioon ei vaja, et ühilduvad kasuliku koormuse täiendused vastuvõtjat ei lõhuks.

Tellijasündmuse kasulik koormus

Tellijasündmused sisaldavad data.subscriber sees tellija praegust esitust:

{
  "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 ja tags on massiivid. Need võivad olla tühjad. Tellija atribuut võib olla ka null, kui väärtust pole, seega peaks vastuvõtja järgima kasuliku koormuse skeemi ega eeldama, et kõik profiili valikulised väärtused on olemas.

Sildisündmuse kasulik koormus

Sildisündmused sisaldavad nii tellijat kui ka sündmuse põhjustanud silti:

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

subscriber.tag_removed puhul tuvastab data.tag endiselt eemaldatud sildi, kuigi seda tellija praeguses tags-massiivis enam pole.

Sündmuse ID-d, edastuse ID-d ja idempotentsus

Sündmuse ID-l ja edastuse ID-l on erinevad eesmärgid.

Sündmuse ID

Sündmuse ID tuvastab ärilise sündmuse. See kuvatakse:

• kasuliku koormuse ülataseme atribuudis id;
• päringu päises X-Maildroppa-Event-Id;
• edastusajaloos.

Sama sündmust võidakse saata mitmele tellinud lõpp-punktile. Need edastused jagavad sama sündmuse ID-d.

Korduskatsed ja käsitsi uuestiedastused säilitavad samuti algse sündmuse ID. Salvesta töödeldud sündmuse ID-d ja muuda äriline tegevus idempotentseks, et korduv päring ei looks topeltkontakte, kordaks pöördumatut tegevust ega rakendaks sama muudatust kaks korda.

Edastuse ID

Edastuse ID tuvastab ühe edastuse kirje. See kuvatakse:

• päringu päises X-Maildroppa-Delivery-Id;
• edastusajaloos.

Igal lõpp-punkti edastusel on oma edastuse ID. Käsitsi uuestiedastus loob uue edastuse ID, säilitades algse sündmuse ID.

Kasuta edastuse ID-d tehniliseks jälgimiseks ja toe jaoks. Kasuta ärilise tasandi duplikaatide vältimiseks sündmuse ID-d.

Õige HTTP-vastuse tagastamine

Maildroppa liigitab vastused järgmiselt:

• mis tahes 2xx-vastus märgib edastuse edukaks;
• 408 Request Timeout, 429 Too Many Requests ja 5xx-vastused on ajutised tõrked ning neid võidakse uuesti proovida;
• ajutised võrgutõrked kuuluvad korduskatsete alla;
• ümbersuunamisi ja muid 3xx-vastuseid ei järgita ning neid käsitletakse lõplike tõrgetena;
• muid 4xx-vastuseid käsitletakse lõplike tõrgetena ja neid ei proovita uuesti.

Tagasta 200, 202 või 204 ainult siis, kui sündmus on turvaliselt vastu võetud. Kui töötlemine võtab aega, salvesta sündmus esmalt ja tagasta edukas vastus enne aeglasema töö asünkroonset tegemist.

Ära tagasta ümbersuunamist teisele webhooki URL-ile. Seadista lõplik URL selle asemel Maildroppas.

Automaatse korduskatse ajakava

Tootmise edastused võivad teha kuni seitse HTTP-katset.

Pärast korratavat tõrget ajastab Maildroppa järgmise katse järgmiste viivitustega:

1. pärast 1. katset: 1 minut
2. pärast 2. katset: 5 minutit
3. pärast 3. katset: 30 minutit
4. pärast 4. katset: 2 tundi
5. pärast 5. katset: 12 tundi
6. pärast 6. katset: 24 tundi

Kui ka 7. katse saab endiselt korratava tõrke, muutub edastus surnud olekusse ja uusi automaatseid katseid ei ajastata.

Ajakava mõõdetakse iga ebaõnnestunud katse hetkest. Tegelik edastusaeg võib olla veidi hilisem, sest edastusi töödeldakse asünkroonselt ja nende suhtes kehtivad ka süsteemi kaitsepiirangud.

Paranda ajutine vastuvõtja probleem võimaluse korral enne kuvatud „Next retry” aega. Kui automaatsed katsed on lõppenud, kasuta pärast vastuvõtja taastumist uuestiedastust.

Edastusajaloo mõistmine

Edastuste ajalugu kuulub parajasti valitud lõpp-punktile. Lõpp-punkti URL kuvatakse jaotise päises, et saaksid kontrollida, millist ajalugu vaatad.

Kasuta järgmisi filtreid:

• All — kuvab tootmis- ja testiedastused;
• Production — kuvab ainult aktiivsete sündmuste edastused;
• Test — kuvab ainult käsitsi tehtud testid.

Kõige uuema oleku hankimiseks klõpsa „Refresh”. Ajalugu ei pea avatuks jätma, kui Maildroppa edastust saadab või uuesti proovib.

Lehel kuvatakse valitud filtri viimased 50 sobivat edastust.

Edastuse veerud

Iga rida sisaldab:

• Created — edastuse kirje loomise aeg;
• State — ootel, edukas, ebaõnnestunud või surnud;
• HTTP — vastuse olek, katsete arv, kestus ja järgmise korduskatse aeg, kui see on kohaldatav;
• Subscriber — tellija e-posti aadress, kui sündmus on tellijaga seotud;
• Delivery — sündmuse tüüp, sündmuse ID ja edastuse ID;
• Actions — uuestiedastus, kui edastus on selleks sobilik.

Kui HTTP-päringut ei tehtud, kuvab HTTP-veerg „No HTTP attempt”. See võib juhtuda siis, kui Maildroppa lükkab päringu enne saatmist tagasi, näiteks kui allkirjastamisvõti puudub või salvestatud sihtkohta ei saa enam turvaliselt kasutada.

Kui see on saadaval, kuvab rida ka vastuvõtja tagastatud vea ja vastuse väljavõtte. Ära tagasta webhooki vastuse kehas saladusi ega tundlikke isikuandmeid, sest osa vastusest võib ilmuda konto edastuslogisse.

Edastuse olekud

Pending tähendab, et edastus ootab esimest katset või ajastatud korduskatset. „Next retry” kuvatakse siis, kui järgmine katse on ajastatud.

Success tähendab, et vastuvõtja tagastas 2xx-vastuse. Uusi automaatseid katseid pole vaja.

Failed tähendab, et edastus lõppes mittekorratava probleemiga, lükati enne HTTP-katset tagasi või peatati enne saatmist.

Dead tähendab, et kõik automaatsed katsed korratava probleemi korral kasutati ära, kuid edukat vastust ei saadud.

Ajaloo säilitamine

Edastuskirjeid säilitatakse piiratud aja jooksul:

• edukad tootmise edastused: 30 päeva;
• ebaõnnestunud tootmise edastused: 90 päeva;
• surnud tootmise edastused: 90 päeva;
• testiedastused: 30 päeva.

Kui vajad pikemat auditiajalugu, säilita oma integratsiooni logisid. Salvesta sündmuse ID-d ja edastuse ID-d, kuid väldi saladuste tarbetut salvestamist.

Edastuse uuestiedastamine

Klõpsa „Replay”, kui lõpetatud tootmise edastust tuleb uuesti proovida.

Uuestiedastus on saadaval olekus Success, Failed või Dead olevatele tootmise edastustele. See pole saadaval, kui edastus on Pending, ja testiedastusi ei saa uuesti edastada.

Uuestiedastus:

• loob uue olekus Pending edastuse;
• loob uue edastuse ID;
• säilitab algse sündmuse ID;
• säilitab algse sündmuse tüübi ja JSON-i kasuliku koormuse;
• kasutab algset salvestatud sihtkoha URL-i ja kohandatud päiste hetktõmmist;
• kasutab uue päringu ettevalmistamisel praegust allkirjastamisvõtit.

Uuestiedastus ei loo kasulikku koormust tellija praegustest andmetest uuesti. See saadab uuesti algse sündmuse hetktõmmise. Nii on uuestiedastus auditeeritav ja välditakse ajaloolise sündmuse tähenduse märkamatut muutumist.

Sama lähteedastuse kohta saab korraga olla ootel ainult üks uuestiedastus. Oota enne uue taotlemist, kuni see uuestiedastus lõpeb.

Enne uuestiedastamist veendu, et lõpp-punkt on aktiivne. Kui lõpp-punkt on mitteaktiivne, ei saa järjekorras olevat uuestiedastust edukalt edastada.

Kuna vastuvõtja võis ärilise tegevuse lõpule viia isegi siis, kui Maildroppa ei saanud selle edukuse vastust, võib uuestiedastus tekitada topeltpäringu. Sündmuse ID alusel duplikaatide vältimine kaitseb ühendatud süsteemi tegevuse kordamise eest.

Lõpp-punkti muutmine

URL-i, sündmuste valiku, kohandatud päiste või aktiivse oleku muutmiseks klõpsa „Edit”.

Enne salvestamist:

1. kinnita, et uus URL on juba kättesaadav;
2. jäta salvestatud päiste väärtused tühjaks, kui need peavad jääma muutmata;
3. sisesta iga ümbernimetatud päise jaoks uus väärtus;
4. vaata sündmuste valik üle, et vajalikud teavitused kogemata eemaldatud ei saaks;
5. salvesta ja saada uus test-webhook.

Pea meeles, et järjekorras olevad edastused säilitavad oma olemasoleva URL-i ja kohandatud päiste hetktõmmise. Testi uut konfiguratsiooni tulevaste edastuste jaoks, mitte ära eelda, et see muudab vanemat järjekorras olevat päringut.

Lõpp-punkti deaktiveerimine

Kasuta On/Off-lülitit, kui soovid integratsiooni peatada ilma selle konfiguratsiooni ja ajaloo kustutamiseta.

Kui lõpp-punkt lülitatakse välja:

• uusi sündmusi selle jaoks enam järjekorda ei lisata;
• ootel edastused, mida pole veel saatmiseks hõivatud, märgitakse ebaõnnestunuks;
• Test keelatakse;
• lõpp-punkt jääb muutmiseks ja hilisemaks aktiveerimiseks kättesaadavaks.

Deaktiveerimise hetkel juba käimas olev päring võib siiski lõpule jõuda. Kui see eristus on sinu integratsiooni jaoks oluline, kontrolli pärast lõpp-punkti väljalülitamist edastuste ajalugu.

Lõpp-punkti mitteaktiivsuse ajal vahele jäänud sündmusi ei täideta tagantjärele, kui selle uuesti sisse lülitad.

Lõpp-punkti kustutamine

Klõpsa „Delete” ja kinnita hoiatus, kui lõpp-punkti pole enam vaja.

Kustutamine eemaldab lõpp-punkti lehelt, peatab tulevased sündmuste edastused ja märgib saatmiseks veel hõivamata ootel edastused ebaõnnestunuks.

Kustutamine ei ole ajutise peatamise viis. Kasuta On/Off-lülitit, kui sul võib konfiguratsiooni või nähtavat ajalugu hiljem jälle vaja minna.

Enne kustutamist pane kirja kõik sündmuse ID-d või edastuse ID-d, mida integratsiooni auditi jaoks veel vajad.

Tõrkeotsing

Lõpp-punkti ei saa salvestada

Kontrolli, et:

• URL algaks väärtusega https://;
• URL kasutaks avalikku hostinime ja porti 443;
• URL ei sisaldaks muutujaid, sisselogimisandmeid ega fragmenti;
• vähemalt üks sündmus oleks valitud;
• igal kohandatud päisel oleks kordumatu nimi ja väärtus;
• reserveeritud Maildroppa ja HTTP päiseid ei kasutataks kohandatud nimedena.

Test on keelatud

Test on saadaval ainult aktiivsele lõpp-punktile. Lülita lõpp-punkt sisse või muuda seda ja vali „Active”, seejärel salvesta enne testimist.

Test ei näita HTTP-katset

Genereeri allkirjastamisvõti, kui olek on „Puudub”. Kontrolli ka, kas sihtkoha hostinimi on avalik ja lahendub endiselt õigesti.

Päring võidakse enne saatmist tagasi lükata, kui selle võti, URL, kohandatud päised või sihtkoha turvakontroll on vigane.

Vastuvõtja tagastab 401 või 403

Kontrolli salvestatud kohandatud päise nime ja mandaati. Muuda lõpp-punkti ja sisesta väärtus uuesti, kui see on muutunud.

Samuti veendu, et vastuvõtja ei ajaks oma API mandaati segi Maildroppa allkirjaga. Kohandatud autoriseerimispäisel ja X-Maildroppa-Signature-l on erinevad eesmärgid ning neid saab eraldi kontrollida.

Vastuvõtja tagastab ümbersuunamise

Maildroppa ei järgi ümbersuunamisi. Asenda lõpp-punkti URL lõpliku avaliku HTTPS-URL-iga ja testi uuesti.

Allkiri ei ühti

Kinnita, et vastuvõtja:

• kasutab praegust allkirjastamisvõtit;
• kasutab täpset X-Maildroppa-Timestamp-i väärtust;
• allkirjastab <timestamp>.<raw request body>;
• kasutab HMAC-SHA256 ja väiketähtedega kuueteistkümnendsüsteemi väljundit;
• võrdleb täielikku väärtust koos v1=-ga;
• teeb võrdluse enne, kui JSON-i parsimine keha muudab.

Sama sündmus saabub mitu korda

See võib juhtuda pärast võrgukatkestust, korduskatset või käsitsi uuestiedastust. Webhooki edastussüsteemide puhul on tavapärane vähemalt ühe korra edastus, mitte täpselt ühe korra edastus.

Kasuta sündmuse ID-d idempotentsusvõtmena. Tagasta 2xx-vastus, kui juba töödeldud sündmuse ID saabub uuesti ja täiendavat tegevust pole vaja.

Edastus on ootel

Vaata HTTP-veergu „Next retry”. Korratav 408, 429, 5xx või ajutine võrgutõrge jätab edastuse olekusse Pending kuni järgmise ajastatud katseni.

Klõpsa pärast korduskatse aega „Refresh”, et laadida uusim olek.

Edastus on surnud

Kõik automaatsed katsed on kasutatud. Paranda esmalt vastuvõtja, veendu, et lõpp-punkt on aktiivne, saada test-webhook ja kasuta seejärel tootmise edastusel käsku Replay.

Soovituslik tootmise kontrollnimekiri

Enne lõpp-punktile tootmises tuginemist kinnita kõik järgmised punktid:

1. Vastuvõtja kasutab stabiilset avalikku HTTPS-URL-i kehtiva sertifikaadiga.
2. Allkirjastamisvõtit säilitatakse lähtekoodist väljaspool.
3. Allkirja kontrollitakse muutmata töötlemata keha põhjal.
4. Vanad ajatemplid lükatakse tagasi dokumenteeritud lubatud ajavahemiku alusel.
5. Vastuvõtja salvestab sündmuse ID-d ja väldib nende duplikaattöötlust.
6. Vastuvõtja logib jälgimiseks sündmuse ID-d ja edastuse ID-d.
7. Aeglane töötlemine toimub pärast sündmuse püsivat vastuvõtmist.
8. 2xx-vastus tagastatakse ainult vastu võetud sündmuste korral.
9. Kohandatud mandaate säilitatakse päistes, mitte URL-is.
10. Valitud on ainult vajalikud sündmustüübid.
11. Test-webhook õnnestub ja kuvatakse edastusajaloos õigesti.
12. Jälgimine teavitab sind, kui tootmise edastused hakkavad tõrkeid tagastama.

Nende kaitsemeetmete abil pakub webhookide leht usaldusväärse integratsiooni mõlemat poolt: turvalist sündmuste edastamist sinu rakendusse ja selget toimimisajalugu Maildroppas.