Stilla vefkróka

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

Vefkrókar gera Maildroppa kleift að láta annað forrit vita þegar eitthvað mikilvægt gerist á reikningnum þínum.

Í stað þess að spyrja Maildroppa í sífellu hvort áskrifandi hafi verið stofnaður, uppfærður, afskráður eða fengið merki getur forritið þitt tekið við HTTPS-beiðni stuttu eftir að atburðurinn á sér stað.

Síðan Webhooks er miðlægur staður fyrir þessa samþættingu á öllum reikningnum. Þú getur búið til marga endapunkta, valið hvaða atburði hver endapunktur tekur við, bætt við auðkenningarhausum, prófað tenginguna, skoðað tilraunir til afhendingar og endurspilað framleiðsluatburð þegar þess þarf.

Hvernig vefkrókar reiknings virka

Vefkrókur reiknings fylgir þessu ferli:

1. Atburður á sér stað í Maildroppa, til dæmis þegar áskrifandi er stofnaður.
2. Maildroppa finnur alla virka endapunkta sem eru áskrifendur að þeim atburði.
3. Maildroppa býr til eina afhendingu fyrir hvern samsvarandi endapunkt.
4. JSON-farmurinn er undirritaður með undirritunarleyndarmáli vefkróka reikningsins þíns.
5. Maildroppa sendir HTTPS POST-beiðni á vistaða vefslóð endapunktsins.
6. Endapunkturinn þinn staðfestir undirskriftina, geymir eða vinnur úr atburðinum og skilar HTTP-svari.
7. Maildroppa skráir niðurstöðuna í afhendingarferil og reynir sjálfkrafa aftur við tímabundnar bilanir.

Ef margir endapunktar eru áskrifendur að sama atburði tekur hver endapunktur við sinni eigin afhendingu. Viðskiptaatburðurinn hefur sama atburðaauðkenni fyrir þá alla, en hver afhending hefur sitt eigið afhendingarauðkenni.

Vefkrókar reiknings eru frábrugðnir skrefi af gerðinni „Send a webhook“ inni í sjálfvirkni. Vefkrókar reiknings hlusta eftir völdum atburðum á reikningnum alls staðar í Maildroppa. Vefkrókur í sjálfvirkni er aðeins sendur þegar áskrifandi nær því tiltekna skrefi. Báðir nota undirritunarleyndarmál reikningsins fyrir vefkróka, þannig að ef leyndarmálinu er skipt út hefur það áhrif á alla móttakendur útsendra vefkróka sem staðfesta undirskriftir Maildroppa.

Opna síðan Vefkrókar

Opnaðu „Settings“, flettu út „Developers“ og veldu „Webhooks“.

Síðan inniheldur þrjú meginsvæði:

• Undirritunarleyndarmál
• Endapunktar
• Afhendingarferill fyrir valinn endapunkt

Þegar þú ert með fleiri en einn endapunkt skaltu velja röð endapunkts til að birta afhendingarferil hans. Ef þú hefur ekki valið endapunkt sérstaklega sýnir Maildroppa feril fyrsta endapunktsins á listanum.

Áður en þú býrð til endapunkt

Settu upp móttakanda á netþjóninum þínum áður en þú stillir Maildroppa. Móttakandinn ætti að:

• Vera aðgengilegur í gegnum opinbera HTTPS-vefslóð.
• Taka við POST-beiðnum með application/json-beiðnismáli.
• Varðveita óunna beiðnismálið þar til undirskrift Maildroppa hefur verið staðfest.
• Skila aðeins 2xx-stöðu eftir að atburðurinn hefur verið samþykktur á öruggan hátt.
• Vinna endurteknar afhendingar með idempotent-hætti með því að nota atburðaauðkennið.
• Svara hratt í stað þess að framkvæma hæga vinnslu meðan á beiðninni stendur.

Áreiðanlegt mynstur er að staðfesta beiðnina, geyma atburðaauðkennið og farminn í varanlegri biðröð eða gagnagrunni, skila 200 eða 204 og vinna síðan úr viðskiptaaðgerðinni.

Ekki afhjúpa þróunartölvu, vistfang á staðarneti eða óvarða skriftu sem framleiðslumóttakanda vefkróka. Maildroppa tekur aðeins við opinberum HTTPS-markmiðum og athugar áfangastaðinn aftur þegar afhending er send.

Skref 1: Búðu til undirritunarleyndarmálið

Sérhver vefkrókabeiðni frá Maildroppa er undirrituð. Móttakandinn þinn notar undirritunarleyndarmálið til að staðfesta að Maildroppa hafi búið til beiðnina og að málinu hafi ekki verið breytt í flutningi.

Efst á síðunni sýnir spjaldið fyrir undirritunarleyndarmál eitt af þessum ástandum:

• Missing — Ekkert undirritunarleyndarmál er til enn.
• Ready — Undirritunarleyndarmál hefur verið stillt.
• Loading — Maildroppa sækir núverandi stöðu.

Smelltu á „Generate secret“ þegar staðan er Missing.

Maildroppa birtir nýja leyndarmálið samstundis. Það byrjar á whsec_. Smelltu á „Copy“ og geymdu það í leyndarmálastjóra eða verndaðri umhverfisstillingu sem móttakandinn þinn notar.

Gildið í heild sinni birtist aðeins strax eftir stofnun eða endurnýjun. Þegar þú endurhleður síðuna eða ferð frá henni sýnir Maildroppa aðeins að leyndarmál sé til og hvenær það var síðast uppfært. Það birtir vistaða leyndarmálið ekki aftur.

Ef þú týnir leyndarmálinu

Ef móttakandinn hefur ekki lengur núverandi leyndarmál skaltu smella á „Rotate secret“ og vista nýja gildið sem birtist.

Útskipti leyndarmálsins kemur í stað fyrra leyndarmálsins samstundis. Maildroppa geymir ekki bæði gildin í aðlögunartímabili. Uppfærðu alla móttakendur sem nota þetta reikningsleyndarmál áður en þú sendir fleiri prófanir eða treystir á afhendingar í framleiðslu.

Nýjar afhendingar, áætlaðar endurtekningartilraunir, prófanir og endurspilanir eru undirritaðar með núverandi leyndarmáli þegar HTTP-beiðnin er send. Þetta þýðir að afhending sem var búin til fyrir útskipti getur samt verið undirrituð með nýja leyndarmálinu þegar reynt er að senda hana síðar.

Komdu fram við leyndarmálið eins og lykilorð

Ekki setja undirritunarleyndarmálið í vafrakóða, opinbera geymslu, vefslóð, villusíðu eða venjulega forritaskrá.

Aðeins móttakandinn á netþjónshliðinni þarf leyndarmálið. Ef þú telur að það hafi komist í hendur annarra skaltu skipta um það og uppfæra alla móttakendur samstundis.

Staðfesting á undirskrift vefkróka

Hver beiðni inniheldur þessa Maildroppa-hausa:

• X-Maildroppa-Event-Id — Auðkennir viðskiptaatburðinn.
• X-Maildroppa-Delivery-Id — Auðkennir þessa tilteknu afhendingu.
• X-Maildroppa-Timestamp — Tími undirritunar sem Unix-sekúndur.
• X-Maildroppa-Signature — HMAC-undirskrift með útgáfustýringu.

Maildroppa sendir einnig:

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

Undirskriftin er á þessu sniði:

v1=<lowercase hexadecimal HMAC>

Maildroppa býr hana til með HMAC-SHA256. Undirritað efni er tímastimpillinn, síðan punktur, síðan nákvæm óunnin JSON-beiðni:

<timestamp>.<raw request body>

Notaðu undirritunarleyndarmálið sem HMAC-lykil.

Eftirfarandi Node.js-dæmi sýnir nauðsynlega staðfestingu. rawBody verður að vera upphaflegu bæti beiðninnar, ekki JSON sem hefur þegar verið þáttaþáttað og raðað aftur.

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

Eftir að undirskriftin hefur verið staðfest skaltu einnig bera tímastimpilinn saman við tíma netþjónsins. Hafnaðu beiðnum utan stutts vikmarks sem þú velur fyrir innviði þína, til dæmis fimm mínútna. Þetta dregur úr hættunni á að gild beiðni sem hefur verið hleruð sé endurspiluð miklu síðar.

Þáttaþáttaðu og vinndu úr JSON aðeins eftir að báðar athuganir hafa staðist.

Algengar orsakir undirskriftarvillna

Undirskrift mistekst yfirleitt af einni af þessum ástæðum:

• Móttakandinn notar gamalt leyndarmál eftir útskipti.
• Millihugbúnaður þáttaþáttaði eða breytti JSON áður en undirskriftin var reiknuð.
• Móttakandinn undirritar aðeins málið og sleppir <timestamp>..
• Tímastimpillinn er meðhöndlaður sem sniðin dagsetning í stað nákvæmlega gildis haussins.
• v1=-forskeytinu er sleppt í samanburðinum.
• Reiknaða HMAC-gildið er kóðað á annan hátt en með lágstöfum í sextándakerfi.

Skráðu atburðaauðkennið og afhendingarauðkennið þegar staðfesting mistekst, en aldrei undirritunarleyndarmálið eða viðkvæm gildi sérsniðinna hausa.

Skref 2: Bættu við endapunkti

Smelltu á „Add endpoint“ í hlutanum Endapunktar.

Ritillinn inniheldur fjóra hluta:

• Vefslóð endapunkts
• Atburðir
• Sérsniðnir hausar
• Virk staða

Nýir endapunktar byrja sem Active og allir atburðir sem birtast í ritlinum eru valdir í upphafi. Farðu yfir valið áður en þú vistar svo móttakandinn fái aðeins þær tilkynningar sem hann þarf í raun.

Stilling vefslóðar endapunkts

Sláðu inn alla opinbera vefslóðina sem á að taka við beiðnum frá Maildroppa, til dæmis:

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

Vefslóðin verður að uppfylla þessar kröfur:

• Hún verður að nota https://.
• Hún verður að innihalda gilt opinbert hýsingarheiti.
• Hún má vera allt að 2.048 stafir að lengd.
• Hún má ekki innihalda sniðbreytur með { eða }.
• Hún má ekki innihalda notandanafn eða lykilorð á undan hýsingarheitinu.
• Hún má ekki innihalda brot sem byrjar á #.
• Hún verður að nota staðlaða HTTPS-gátt 443.
• Hún má ekki nota localhost, hrátt IP-vistfang eða hýsingarheiti sem leysist upp í lokað einkanet eða frátekið net.

Fyrirspurnarstikar eru studdir, en ekki setja API-lykla eða önnur leyndarmál í vefslóðina. Vefslóðir sjást á lista endapunkta og í afhendingargögnum. Notaðu sérsniðinn haus fyrir auðkenni í staðinn.

Maildroppa fylgir ekki tilvísunum. Vistaðu lokaáfangastaðinn með HTTPS í stað vefslóðar sem skilar 301, 302, 307 eða 308.

Hýsingarheiti áfangastaðarins er leyst upp aftur áður en sending fer fram. Hýsingarheiti sem leysist síðar upp í einka- eða lokað vistfang er hafnað, jafnvel þótt það hafi verið gilt þegar endapunkturinn var vistaður.

Val á atburðum

Veldu að minnsta kosti einn atburð. Endapunktur tekur aðeins við þeim atburðategundum sem valdar eru í ritli hans.

Síðan býður upp á þessi atburðaval:

Áskrifandi stofnaður — subscriber.created

Sendist þegar áskrifandi er stofnaður á Maildroppa-reikningnum.

Notaðu þennan atburð til að búa til samsvarandi tengilið í CRM-kerfi, gagnavettvangi viðskiptavina, innri gagnagrunni eða öðru kerfi sem tekur mið af heimildum.

Ekki túlka þennan atburð sem sönnun þess að hver skráning hafi lokið tvöfaldri staðfestingu. Staða áskrifandans í farminum lýsir núverandi ástandi.

Áskrifandi uppfærður — subscriber.updated

Sendist þegar innbyggðar upplýsingar um áskrifanda eða gildi sérsniðinna reita breytast.

Notaðu heildarhlut áskrifandans í farminum sem núverandi framsetningu Maildroppa. Forðastu að gera ráð fyrir að aðeins einn tiltekinn eiginleiki hafi breyst.

Úthlutun og fjarlæging merkja hafa sínar eigin atburðategundir svo hægt sé að meðhöndla þær sérstaklega.

Áskrifandi afskráður — subscriber.unsubscribed

Sendist þegar áskrifandi fer í afskráða stöðu í gegnum afskráningaraðgerð.

Notaðu þennan atburð til að útiloka tengiliðinn í tengdum kerfum. Ekki skrá viðkomandi sjálfkrafa aftur vegna þess að annað kerfi merkir tengiliðinn enn sem virkan.

Merki bætt við — subscriber.tag_added

Sendist þegar merki er úthlutað á áskrifanda.

Farmurinn inniheldur áskrifandann og merkið sem tengjast þessari tilteknu breytingu.

Merki fjarlægt — subscriber.tag_removed

Sendist þegar merki er fjarlægt af áskrifanda.

Farmurinn inniheldur uppfærðan áskrifanda og fjarlægða merkið. Fjarlægða merkið er gefið upp sérstaklega þótt það sé ekki lengur í núverandi tags-fylki áskrifandans.

Eyðublað sent inn — form.submitted

Sendist þegar gestur sendir inn skráningareyðublað frá Maildroppa.

Líttu á þetta sem merki um innsendingu eyðublaðs, ekki staðfestingu á að tvöfaldri staðfestingu hafi verið lokið. Hvers kyns verkflæði sem krefst staðfestrar áskriftar verður áfram að virða núverandi stöðu áskrifandans og staðfestingarferlið.

Notaðu aðskilda endapunkta þegar ábyrgð er ólík

Þú getur sent ólíka atburði til ólíkra kerfa. Til dæmis:

• Sendu áskrifenda- og merkiatburði til CRM-kerfis.
• Sendu afskráningaratburði til útilokunarþjónustu.
• Sendu innsendingaratburði eyðublaða í greiningarferli.

Aðskildir endapunktar draga úr óþarfa umferð og auðvelda bilanagreiningu. Hver endapunktur hefur sitt eigið atburðaval, vefslóð, sérsniðna hausa, virku stöðu, prófanir og afhendingarferil.

Að bæta við sérsniðnum hausum

Sérsniðnir hausar eru valfrjálsir. Notaðu þá þegar móttakandinn krefst API-lykils, bearer-tákns, auðkennis leigutaka eða annars fasts hauss.

Smelltu á „Add header“ og sláðu síðan inn heiti og gildi haussins. Hentug dæmi eru:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Þú getur bætt við allt að 20 sérsniðnum hausum.

Heiti hausa:

• Eru nauðsynleg.
• Geta innihaldið allt að 128 stafi.
• Verða að nota gilda stafi fyrir HTTP-hausanöfn.
• Verða að vera einstök án tillits til há- og lágstafa.

Gildi hausa:

• Eru nauðsynleg.
• Geta innihaldið allt að 2.000 stafi.
• Mega ekki innihalda línuskiptingar.

Eftirfarandi heiti eru frátekin og ekki er hægt að skipta þeim út með sérsniðnum haus:

• Content-Type
• Content-Length
• Host
• User-Agent
• Öll heiti sem byrja á X-Maildroppa-

Þetta kemur í veg fyrir að sérsniðið gildi komi í stað afhendingar- og undirskriftarhausa Maildroppa.

Hvernig hausleyndarmál eru geymd

Maildroppa dulkóðar gildi sérsniðinna hausa áður en þau eru geymd. Vistuð gildi eru ekki send aftur í vafrann á læsilegu formi.

Þegar þú breytir endapunktinum síðar sýnir gildisreiturinn „Stored value kept“. Skildu hann eftir auðan þegar núverandi leyndarmál á að vera óbreytt. Sláðu inn nýtt gildi til að skipta því út.

Ef þú breytir heiti haussins skaltu slá gildið inn aftur. Maildroppa heldur aðeins vistuðu leyndarmáli meðan upphaflegt heiti haussins helst óbreytt.

Ef hauslína er fjarlægð er sá haus fjarlægður úr komandi afhendingum eftir að endapunkturinn er vistaður.

Sérsniðin hausgildi eru meðhöndluð sem viðkvæm í vistuðum beiðnaupplýsingum. Þau eru hulin í stað þess að birtast í afhendingarferli.

Að stilla endapunkt sem virkan eða óvirkan

Hafðu „Active“ valið þegar endapunkturinn er tilbúinn til að taka strax við atburðum.

Afveltu það þegar þú vilt vista stillinguna án þess að hefja afhendingar. Þú getur virkjað endapunktinn síðar af lista endapunkta.

Óvirkur endapunktur:

• Tekur ekki við nýjum atburðum.
• Getur ekki sent prófunarvefkrók.
• Er áfram sýnilegur og hægt er að breyta honum.
• Heldur núverandi afhendingarferli aðgengilegum.

Virkjun endapunkts sækir ekki aftur atburði sem áttu sér stað meðan hann var óvirkur.

Smelltu á „Save“ þegar vefslóð, atburðaval, hausar og staða eru rétt.

Skilningur á lista endapunkta

Hver röð endapunkts sýnir:

• Vefslóð áfangastaðarins.
• Active- eða Inactive-merki.
• Áskrifnar atburðategundir.
• Fjölda sérsniðinna hausa.
• Tímann þegar endapunkturinn var síðast uppfærður.

Tiltækar aðgerðir eru:

• On/Off — Virkjar eða gerir endapunktinn óvirkan.
• Test — Sendir eina prófunarbeiðni strax á virkan endapunkt.
• Edit — Breytir vefslóð, atburðum, hausum eða virkri stöðu.
• Delete — Fjarlægir stillingu endapunkts varanlega eftir staðfestingu.

Veldu meginhluta raðar til að opna afhendingarferil þess endapunkts fyrir neðan listann.

Hvernig vistaðar breytingar hafa áhrif á fyrirliggjandi afhendingar

Atburður á reikningi býr til afhendingu með skyndimynd af vefslóð endapunkts, farmi og sérsniðnum hausum á þeim tíma.

Breyting á vefslóð eða sérsniðnum hausum hefur áhrif á nýjar afhendingar. Afhending sem þegar hefur verið sett í bið heldur upphaflegum áfangastað og vistuðum hausastillingum.

Breyting á völdum atburðum hefur einnig aðeins áhrif á atburði sem eiga sér stað síðar. Maildroppa býr ekki afturvirkt til afhendingar fyrir atburðategundir sem voru ekki valdar þegar atburðurinn átti sér stað.

Undirritunarleyndarmálið er öðruvísi: það er lesið þegar HTTP-beiðnin er undirbúin. Afhending í bið eða endurspilun getur því notað nýtt undirritunarleyndarmál, jafnvel þegar farmur hennar og skyndimynd endapunkts voru búin til fyrr.

Prófun á endapunkti

Smelltu á „Test“ á virkum endapunkti eftir að móttakandinn og undirritunarleyndarmálið eru tilbúin.

Maildroppa sendir samstundis eina undirritaða beiðni með vistuðu vefslóðinni og vistuðum sérsniðnum hausum. Óvistaðar breytingar í opnum ritli eru ekki hluti af prófuninni.

Prófunarfarmurinn notar atburðategundina webhook.test og stillir livemode á 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."
  }
}

Mynduð auðkenni og tímastimpill eru ólík í hverri raunverulegri prófun.

Prófun gerir nákvæmlega eina HTTP-tilraun. Prófunarafhendingar fara ekki á endurtekningaráætlun framleiðslu og ekki er hægt að endurspila þær.

Þegar beiðninni lýkur sýnir niðurstöðuspjaldið:

• Test success eða Test failed
• Atburðaauðkenni
• HTTP-stöðu, þegar svar barst
• Tímalengd
• Afhendingarauðkenni
• Villuupplýsingar, þegar þær eru tiltækar
• Útdrátt úr svari, þegar móttakandinn skilaði meginmáli

Prófunin birtist einnig í afhendingarferli með Test-merki. Notaðu „Test“-síuna til að sýna aðeins prófunarbeiðnir.

Skilningur á framleiðslufarmi

Framleiðsluatburðir reiknings nota sameiginlegt JSON-umslag:

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

Eiginleikar efsta stigsins þýða:

• id — Atburðaauðkennið. Það samsvarar X-Maildroppa-Event-Id.
• type — Atburðalykillinn sem valinn var í ritli endapunktsins.
• schema_version — Útgáfa farmsskemans. Notaðu hana þegar þú ákveður hvernig á að þáttaþátta atburðinn.
• created_at — Tíminn þegar atburðarfarmurinn var búinn til, í UTC.
• livemode — true fyrir framleiðsluatburði og false fyrir prófunaratburði.
• data — Atburðarsértækt efni.

Beindu atburðum eftir nákvæmu type-gildi. Hunsaðu viðbótareiginleika sem samþættingin þín þarf ekki svo viðbætur við samhæfan farm brjóti ekki móttakandann.

Farmur áskrifendaatburðar

Áskrifendaatburðir innihalda núverandi framsetningu áskrifandans í 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 og tags eru fylki. Þau geta verið tóm. Eiginleiki áskrifanda getur einnig verið null þegar ekkert gildi er til staðar, svo móttakandinn ætti að fylgja farmsskemanu í stað þess að gera ráð fyrir að hvert valfrjálst prófílgildi sé til staðar.

Farmur merkiatburðar

Merkiatburðir innihalda bæði áskrifandann og merkið sem olli atburðinum:

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

Fyrir subscriber.tag_removed auðkennir data.tag enn fjarlægða merkið, jafnvel þótt núverandi tags-fylki áskrifandans innihaldi það ekki lengur.

Atburðaauðkenni, afhendingarauðkenni og idempotency

Atburðaauðkennið og afhendingarauðkennið þjóna ólíkum tilgangi.

Atburðaauðkenni

Atburðaauðkennið auðkennir viðskiptaatburðinn. Það birtist í:

• id-eiginleika efsta stigs farmsins.
• X-Maildroppa-Event-Id-beiðnihausnum.
• Afhendingarferli.

Sami atburður getur verið sendur til margra áskrifinna endapunkta. Þessar afhendingar deila atburðaauðkenninu.

Endurtekningartilraunir og handvirkar endurspilanir halda einnig upphaflega atburðaauðkenninu. Geymdu unnin atburðaauðkenni og gerðu viðskiptaaðgerðina idempotent svo endurtekin beiðni stofni ekki til tvítekinna tengiliða, endurtaki óafturkræfa aðgerð eða beiti sömu breytingu tvisvar.

Afhendingarauðkenni

Afhendingarauðkennið auðkennir eina afhendingarskrá. Það birtist í:

• X-Maildroppa-Delivery-Id-beiðnihausnum.
• Afhendingarferli.

Hver afhending á endapunkt hefur sitt eigið afhendingarauðkenni. Handvirk endurspilun býr til nýtt afhendingarauðkenni en heldur upphaflega atburðaauðkenninu.

Notaðu afhendingarauðkennið fyrir tæknilega rekjanleika og aðstoð. Notaðu atburðaauðkennið til að fjarlægja tvítekin viðskipti.

Rétt HTTP-svar

Maildroppa flokkar svör þannig:

• Öll 2xx-svör merkja afhendinguna sem heppnaða.
• 408 Request Timeout, 429 Too Many Requests og 5xx-svör eru tímabundnar bilanir og hægt er að reyna aftur.
• Netbilanir sem geta verið tímabundnar eru endurteknar.
• Tilvísunum og öðrum 3xx-svörum er ekki fylgt og þau eru meðhöndluð sem endanlegar bilanir.
• Önnur 4xx-svör eru meðhöndluð sem endanlegar bilanir og ekki reynt aftur.

Skilaðu 200, 202 eða 204 aðeins þegar atburðurinn hefur verið samþykktur á öruggan hátt. Ef vinnsla tekur tíma skaltu geyma atburðinn fyrst og skila árangurssvari áður en hægari vinnslan fer fram ósamstillt.

Ekki skila tilvísun á aðra vefkrókavefslóð. Stilltu lokaáfangastaðinn í Maildroppa í staðinn.

Sjálfvirk endurtekningaráætlun

Framleiðsluatferðir geta gert allt að sjö HTTP-tilraunir.

Eftir endurtekningarhæfa bilun áætlar Maildroppa næstu tilraun með þessum töfum:

1. Eftir tilraun 1: 1 mínúta
2. Eftir tilraun 2: 5 mínútur
3. Eftir tilraun 3: 30 mínútur
4. Eftir tilraun 4: 2 klukkustundir
5. Eftir tilraun 5: 12 klukkustundir
6. Eftir tilraun 6: 24 klukkustundir

Ef tilraun 7 fær enn endurtekningarhæfa bilun verður afhendingin Dead og engin frekari sjálfvirk tilraun er áætluð.

Áætlunin er mæld frá hverri biluðu tilraun. Raunverulegur afhendingartími getur verið örlítið síðar vegna þess að afhendingar eru unnar ósamstillt og lúta einnig verndarmörkum kerfisins.

Leystu tímabundið vandamál hjá móttakandanum fyrir sýndan „Next retry“-tíma þegar þess er kostur. Ef sjálfvirkum tilraunum er lokið skaltu nota Replay eftir að móttakandinn er orðinn heilbrigður á ný.

Skilningur á afhendingarferli

Afhendingarferill tilheyrir endapunktinum sem nú er valinn. Vefslóð endapunktsins birtist í fyrirsögn hlutarins svo þú getir staðfest hvaða feril þú ert að skoða.

Notaðu þessar síur:

• All — Sýnir framleiðslu- og prófunarafhendingar.
• Production — Sýnir aðeins afhendingar lifandi atburða.
• Test — Sýnir aðeins handvirkar prófanir.

Smelltu á „Refresh“ til að sækja nýjustu stöðuna. Ekki þarf að hafa ferilinn opinn meðan Maildroppa sendir eða reynir aftur afhendingu.

Síðan sýnir síðustu 50 samsvarandi afhendingar fyrir valda síu.

Dálkar afhendingar

Hver röð inniheldur:

• Created — Hvenær afhendingarskráin var búin til.
• State — Pending, Success, Failed eða Dead.
• HTTP — Svarstaða, fjöldi tilrauna, tímalengd og næsti endurtekningartími þegar það á við.
• Subscriber — Netfang áskrifanda þegar atburðurinn tengist áskrifanda.
• Delivery — Atburðategund, atburðaauðkenni og afhendingarauðkenni.
• Actions — Replay þegar afhendingin uppfyllir skilyrði.

Ef engin HTTP-beiðni var send sýnir HTTP-dálkurinn „No HTTP attempt“. Þetta getur gerst þegar Maildroppa hafnar beiðninni áður en hún er send, til dæmis vegna þess að undirritunarleyndarmál vantar eða vistaðan áfangastað er ekki lengur hægt að nota á öruggan hátt.

Þegar það er tiltækt sýnir röðin einnig Error og Response excerpt sem móttakandinn skilaði. Ekki skila leyndarmálum eða viðkvæmum persónuupplýsingum í svari vefkróka vegna þess að hluti þess svars getur birst í afhendingarskrá reikningsins.

Ástand afhendingar

Pending þýðir að afhendingin bíður fyrstu tilraunar eða áætlaðrar endurtekningar. „Next retry“ birtist þegar önnur tilraun hefur verið áætluð.

Success þýðir að móttakandinn skilaði 2xx-svari. Engin frekari sjálfvirk tilraun er nauðsynleg.

Failed þýðir að afhendingunni lauk vegna óendurtekningarhæfs vanda, henni var hafnað áður en HTTP-tilraun var gerð eða hún stöðvuð áður en hægt var að senda hana.

Dead þýðir að allar sjálfvirkar tilraunir vegna endurtekningarhæfs vanda voru notaðar án þess að árangurssvar bærist.

Varðveisla ferils

Afhendingarskrár eru geymdar í takmarkaðan tíma:

• Heppnaðar framleiðsluafhendingar: 30 dagar
• Misheppnaðar framleiðsluafhendingar: 90 dagar
• Dauðar framleiðsluafhendingar: 90 dagar
• Prófunarafhendingar: 30 dagar

Geymdu eigin samþættingarskrár þegar þú þarft lengri endurskoðunarferil. Geymdu atburðaauðkenni og afhendingarauðkenni, en forðastu að geyma leyndarmál að óþörfu.

Endurspilun afhendingar

Smelltu á „Replay“ þegar lokiðri framleiðsluafhendingu ætti að reyna aftur.

Replay er í boði fyrir framleiðsluafhendingar í ástandinu Success, Failed eða Dead. Það er ekki í boði meðan afhending er Pending og ekki er hægt að endurspila prófunarafhendingar.

Endurspilun:

• Býr til nýja afhendingu í Pending.
• Býr til nýtt afhendingarauðkenni.
• Heldur upphaflega atburðaauðkenninu.
• Heldur upphaflegri atburðategund og JSON-farmi.
• Notar upphaflega vistaða vefslóð markmiðsins og skyndimynd sérsniðinna hausa.
• Notar núverandi undirritunarleyndarmál þegar nýja beiðnin er undirbúin.

Endurspilun byggir ekki farminn upp að nýju út frá núverandi gögnum áskrifandans. Hún sendir upphaflegu skyndimynd atburðarins aftur. Þetta gerir endurspilun rekjanlega og kemur í veg fyrir að sögulegur atburður breyti merkingu sinni hljóðlega.

Aðeins ein endurspilun sama upprunalega afhendingar getur verið Pending í einu. Bíddu þar til þeirri endurspilun lýkur áður en þú biður um aðra.

Gakktu úr skugga um að endapunkturinn sé Active áður en þú endurspilar. Ef endapunkturinn er óvirkur er ekki hægt að afhenda biðraða endurspilun með góðum árangri.

Þar sem móttakandi kann að hafa lokið viðskiptaaðgerðinni þótt Maildroppa hafi ekki fengið árangurssvarið sitt getur endurspilun valdið tvítekinni beiðni. Fjarlæging tvítekinna atburða eftir atburðaauðkenni ver tengda kerfið gegn því að aðgerðin sé endurtekin.

Breyting á endapunkti

Smelltu á „Edit“ til að breyta vefslóð, atburðavali, sérsniðnum hausum eða virkri stöðu.

Áður en þú vistar:

1. Staðfestu að nýja vefslóðin sé þegar aðgengileg.
2. Skildu vistuð hausgildi eftir auð þegar þau eiga að haldast óbreytt.
3. Sláðu inn nýtt gildi fyrir hvert hausheiti sem hefur verið endurnefnt.
4. Farðu yfir atburðavalið svo nauðsynlegar tilkynningar séu ekki fjarlægðar fyrir slysni.
5. Vistaðu og sendu nýjan prófunarvefkrók.

Mundu að biðraðar afhendingar halda núverandi vefslóð og skyndimynd sérsniðinna hausa. Prófaðu nýju stillinguna fyrir komandi afhendingar í stað þess að gera ráð fyrir að hún breyti eldri biðraðri beiðni.

Slökkt á endapunkti

Notaðu On/Off-rofa þegar þú vilt gera samþættingu tímabundið óvirka án þess að eyða stillingu hennar og ferli.

Þegar slökkt er á endapunkti:

• Nýir atburðir eru ekki lengur settir í bið fyrir hann.
• Pending-afhendingar sem ekki hafa þegar verið teknar til sendingar eru merktar Failed.
• Test er óvirkt.
• Endapunkturinn er áfram tiltækur til breytinga og síðar virkjunar.

Beiðni sem þegar er í gangi þegar slökkt er á endapunktinum getur samt lokið. Athugaðu afhendingarferilinn eftir að slökkt er á endapunktinum ef þessi aðgreining skiptir máli fyrir samþættinguna þína.

Atburðir sem fara fram hjá endapunkti meðan hann er óvirkur eru ekki sóttir aftur þegar þú kveikir á honum á ný.

Eyðing endapunkts

Smelltu á „Delete“ og staðfestu viðvörunina þegar endapunkturinn á ekki lengur að vera til.

Eyðing fjarlægir endapunktinn af síðunni, stöðvar komandi afhendingar atburða og merkir Pending-afhendingar sem ekki höfðu þegar verið teknar til sendingar sem Failed.

Delete er ekki leið til tímabundinnar stöðvunar. Notaðu On/Off-rofa þegar þú gætir þurft stillinguna eða sýnilegan feril hennar aftur.

Áður en þú eyðir skaltu skrá öll atburðaauðkenni eða afhendingarauðkenni sem þú þarft enn fyrir endurskoðun samþættingarinnar.

Bilanagreining

Ekki er hægt að vista endapunktinn

Athugaðu að:

• Vefslóðin byrji á https://.
• Vefslóðin noti opinbert hýsingarheiti og gátt 443.
• Vefslóðin innihaldi engar breytur, innskráningarupplýsingar eða brot.
• Að minnsta kosti einn atburður sé valinn.
• Sérhver sérsniðinn haus hafi einstakt heiti og gildi.
• Frátekin Maildroppa- og HTTP-hausheiti séu ekki notuð sem sérsniðin heiti.

Test er óvirkt

Test er aðeins tiltækt fyrir virkan endapunkt. Kveiktu á endapunktinum eða breyttu honum og veldu „Active“, vistaðu síðan áður en þú prófar.

Test sýnir enga HTTP-tilraun

Búðu til undirritunarleyndarmál ef staðan er Missing. Athugaðu einnig hvort hýsingarheiti áfangastaðarins sé opinbert og leysist enn rétt upp.

Beiðni getur verið hafnað áður en hún er send ef leyndarmál hennar, vefslóð, sérsniðnir hausar eða öryggisathugun á áfangastað er ógild.

Móttakandinn skilar 401 eða 403

Athugaðu vistað heiti sérsniðna haussins og auðkennið. Breyttu endapunktinum og sláðu gildið inn aftur ef það hefur breyst.

Gakktu einnig úr skugga um að móttakandinn rugli ekki saman eigin API-auðkenni og Maildroppa-undirskriftinni. Sérsniðinn heimildarhaus og X-Maildroppa-Signature þjóna ólíkum tilgangi og hægt er að athuga þá óháð.

Móttakandinn skilar tilvísun

Maildroppa fylgir ekki tilvísunum. Skiptu út vefslóð endapunktsins fyrir lokaáfangastaðinn með opinberu HTTPS og prófaðu aftur.

Undirskriftin passar ekki

Staðfestu að móttakandinn:

• Noti núverandi undirritunarleyndarmál.
• Noti nákvæmt X-Maildroppa-Timestamp-gildi.
• Undirriti <timestamp>.<raw request body>.
• Noti HMAC-SHA256 og lágstafaúttak í sextándakerfi.
• Beri saman allt gildið, þar á meðal v1=.
• Framkvæmi samanburðinn áður en JSON-þáttun breytir málinu.

Sami atburður berst oftar en einu sinni

Þetta getur gerst eftir nettruflun, endurtekningu eða handvirka endurspilun. Eðlilegt er að afhendingarkerfi vefkróka bjóði upp á afhendingu að minnsta kosti einu sinni fremur en nákvæmlega einu sinni.

Notaðu atburðaauðkennið sem idempotency-lykil. Skilaðu 2xx-svari þegar áður unninn atburður berst aftur og ekki er þörf á frekari aðgerð.

Afhending er Pending

Skoðaðu „Next retry“ í HTTP-dálknum. Endurtekningarhæf 408, 429, 5xx eða tímabundin netbilun heldur afhendingunni í Pending þar til næsta áætlaða tilraun fer fram.

Smelltu á „Refresh“ eftir endurtekningartímann til að hlaða nýjustu stöðunni.

Afhending er Dead

Allar sjálfvirkar tilraunir hafa verið notaðar. Lagfærðu móttakandann fyrst, gakktu úr skugga um að endapunkturinn sé Active, sendu prófunarvefkrók og notaðu síðan Replay á framleiðsluafhendingunni.

Ráðlagður gátlisti fyrir framleiðslu

Áður en þú treystir á endapunkt í framleiðslu skaltu staðfesta allt eftirfarandi:

1. Móttakandinn notar stöðuga opinbera HTTPS-vefslóð með gildu vottorði.
2. Undirritunarleyndarmálið er geymt utan frumkóðans.
3. Undirskriftin er athuguð gegn óbreyttu óunna málinu.
4. Gömlum tímastimplum er hafnað samkvæmt skjalfestu vikmarki.
5. Móttakandinn geymir og fjarlægir tvítekin atburðaauðkenni.
6. Móttakandinn skráir atburðaauðkenni og afhendingarauðkenni til rekjanleika.
7. Hæg vinnsla fer fram eftir að atburðurinn hefur verið samþykktur varanlega.
8. 2xx-svari er aðeins skilað fyrir samþykkta atburði.
9. Sérsniðin auðkenni eru geymd í hausum en ekki í vefslóðinni.
10. Aðeins nauðsynlegar atburðategundir eru valdar.
11. Prófunarvefkrókur heppnast og birtist rétt í afhendingarferli.
12. Vöktun lætur þig vita þegar villur byrja að berast í framleiðsluafhendingum.

Með þessum öryggisráðstöfunum býður síðan Vefkrókar upp á báðar hliðar áreiðanlegrar samþættingar: örugga afhendingu atburða til forritsins þíns og skýran rekstrarferil inni í Maildroppa.