Konfigurirajte spletne kavlje

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

Spletni kavlji omogočajo, da Maildroppa obvesti drugo aplikacijo, ko se v vašem računu zgodi nekaj pomembnega.

Namesto da Maildroppo vedno znova sprašujete, ali je bil naročnik ustvarjen, posodobljen, odjavljen ali mu je bila dodeljena oznaka, lahko vaša aplikacija kmalu po dogodku prejme zahtevo HTTPS.

Stran Spletni kavlji je osrednje mesto za to integracijo na ravni računa. Ustvarite lahko več končnih točk, izberete dogodke, ki jih posamezna končna točka prejema, dodate glave za preverjanje pristnosti, preizkusite povezavo, pregledate poskuse dostave in po potrebi znova predvajate produkcijski dogodek.

Kako delujejo spletni kavlji računa

Spletni kavelj računa deluje po tem postopku:

1. V Maildroppi se zgodi dogodek, na primer ustvari se naročnik.
2. Maildroppa poišče vse aktivne končne točke, naročene na ta dogodek.
3. Maildroppa ustvari eno dostavo za vsako ustrezno končno točko.
4. Telo JSON je podpisano s skrivnostjo za podpisovanje spletnih kavljev vašega računa.
5. Maildroppa pošlje zahtevo HTTPS POST na shranjeni URL končne točke.
6. Vaša končna točka preveri podpis, shrani ali obdela dogodek ter vrne odgovor HTTP.
7. Maildroppa zabeleži rezultat v zgodovino dostav in samodejno znova poskusi pri začasnih napakah.

Če je na isti dogodek naročenih več končnih točk, vsaka prejme svojo dostavo. Poslovni dogodek ima pri vseh isti ID dogodka, vsaka dostava pa ima svoj ID dostave.

Spletni kavlji računa se razlikujejo od koraka »Pošlji spletni kavelj« znotraj avtomatizacije. Spletni kavlji računa poslušajo izbrane dogodke računa v celotnem Maildroppi. Spletni kavelj avtomatizacije se pošlje samo, ko naročnik doseže ta določen korak. Oba uporabljata skrivnost za podpisovanje spletnih kavljev računa, zato rotacija skrivnosti vpliva na vse prejemnike odhodnih spletnih kavljev, ki preverjajo podpise Maildroppe.

Odpiranje strani Spletni kavlji

Odprite »Nastavitve«, razširite »Razvijalci« in izberite »Spletni kavlji«.

Stran vsebuje tri glavna področja:

• Skrivnost za podpisovanje
• Končne točke
• Zgodovina dostav za izbrano končno točko

Ko imate več kot eno končno točko, izberite vrstico končne točke, da prikažete njeno zgodovino dostav. Če je niste izrecno izbrali, Maildroppa prikaže zgodovino prve končne točke na seznamu.

Pred ustvarjanjem končne točke

Pred konfiguriranjem Maildroppe pripravite prejemnika na svojem strežniku. Prejemnik mora:

• Biti dosegljiv prek javnega URL-ja HTTPS.
• Sprejemati zahteve POST s telesom application/json.
• Ohraniti neobdelano telo zahteve, dokler podpis Maildroppe ni preverjen.
• Vr­niti status 2xx šele, ko je bil dogodek varno sprejet.
• Ponavljajoče se dostave obdelovati idempotentno z uporabo ID-ja dogodka.
• Odgovoriti hitro, namesto da med zahtevo izvaja počasna opravila.

Zanesljiv vzorec je preveriti zahtevo, shraniti ID dogodka in vsebino v trajno čakalno vrsto ali podatkovno zbirko, vrniti 200 ali 204 ter poslovno dejanje obdelati pozneje.

Razvojnega računalnika, lokalnega omrežnega naslova ali nezaščitenega skripta ne izpostavljajte kot produkcijskega prejemnika spletnih kavljev. Maildroppa sprejema samo javne cilje HTTPS in cilj znova preveri, ko pošlje dostavo.

1. korak: ustvarite skrivnost za podpisovanje

---

Vsaka zahteva spletnega kavlja Maildroppe je podpisana. Vaš prejemnik s skrivnostjo za podpisovanje preveri, ali je zahtevo ustvarila Maildroppa in ali vsebina med prenosom ni bila spremenjena.

Na vrhu strani plošča Skrivnost za podpisovanje prikazuje eno od teh stanj:

• Manjka — Skrivnost za podpisovanje še ne obstaja.
• Pripravljeno — Skrivnost za podpisovanje je konfigurirana.
• Nalaganje — Maildroppa pridobiva trenutno stanje.

Ko je stanje Manjka, kliknite »Ustvari skrivnost«.

Maildroppa novo skrivnost prikaže takoj. Začne se z whsec_. Kliknite »Kopiraj« in jo shranite v upravljalnik skrivnosti ali zaščiteno okoljsko konfiguracijo, ki jo uporablja vaš prejemnik.

Celotna vrednost je prikazana samo takoj po ustvarjanju ali rotaciji. Ko stran znova naložite ali jo zapustite, Maildroppa prikaže le, da skrivnost obstaja, in čas zadnje posodobitve. Shranjene skrivnosti ne razkrije več.

Če izgubite skrivnost

Če prejemnik nima več trenutne skrivnosti, kliknite »Zavrti skrivnost« in shranite novo prikazano vrednost.

Rotacija takoj zamenja prejšnjo skrivnost. Maildroppa obe vrednosti ne hrani hkrati za prehodno obdobje. Pred pošiljanjem nadaljnjih preizkusov ali zanašanjem na produkcijske dostave posodobite vse prejemnike, ki uporabljajo to skrivnost računa.

Nove dostave, načrtovani ponovni poskusi, preizkusi in ponovna predvajanja so podpisani s trenutno skrivnostjo ob času zahteve HTTP. To pomeni, da je lahko dostava, ustvarjena pred rotacijo, ob poznejšem poskusu še vedno podpisana z novo skrivnostjo.

S skrivnostjo ravnajte kot z geslom

Skrivnosti za podpisovanje ne vstavljajte v kodo brskalnika, javni repozitorij, URL, stran z napako ali običajen dnevnik aplikacije.

Skrivnost potrebuje samo strežniški prejemnik. Če menite, da je bila razkrita, jo takoj zavrtite in posodobite vse prejemnike.

Preverjanje podpisa spletnega kavlja

Vsaka zahteva vsebuje te glave Maildroppe:

• X-Maildroppa-Event-Id — Identificira poslovni dogodek.
• X-Maildroppa-Delivery-Id — Identificira to določeno dostavo.
• X-Maildroppa-Timestamp — Čas podpisovanja v sekundah Unix.
• X-Maildroppa-Signature — Različicni podpis HMAC.

Maildroppa pošlje tudi:

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

Podpis ima to obliko:

v1=<lowercase hexadecimal HMAC>

Maildroppa ga ustvari z algoritmom HMAC-SHA256. Podpisana vsebina je časovni žig, ki mu sledi pika, nato pa točno neobdelano telo zahteve JSON:

<timestamp>.<raw request body>

Kot ključ HMAC uporabite skrivnost za podpisovanje.

Naslednji primer Node.js prikazuje bistveni korak preverjanja. rawBody mora biti izvirni niz bajtov zahteve, ne JSON, ki je bil že razčlenjen in znova serializiran.

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 preverjanju podpisa primerjajte časovni žig tudi s časom strežnika. Zahteve zunaj kratke tolerance, izbrane za vašo infrastrukturo, na primer petih minut, zavrnite. S tem zmanjšate tveganje, da bi bil veljaven zajeti zahtevek znova predvajan veliko pozneje.

JSON razčlenite in obdelajte šele, ko sta oba preverjanja uspešna.

Pogosti vzroki napak podpisa

Podpis običajno ne uspe iz enega od teh razlogov:

• Prejemnik po rotaciji uporablja staro skrivnost.
• Vmesna programska oprema je JSON razčlenila ali spremenila, preden je bil podpis izračunan.
• Prejemnik podpiše samo telo in izpusti <timestamp>..
• Časovni žig obravnava kot oblikovan datum namesto kot točno vrednost glave.
• Predpona v1= je izpuščena iz primerjave.
• Izračunani HMAC je kodiran drugače, namesto v malih šestnajstiških znakih.

Ko preverjanje ne uspe, zabeležite ID dogodka in ID dostave, vendar nikoli ne beležite skrivnosti za podpisovanje ali občutljivih vrednosti glav po meri.

2. korak: dodajte končno točko

---

V razdelku Končne točke kliknite »Dodaj končno točko«.

Urejevalnik vsebuje štiri dele:

• URL končne točke
• Dogodki
• Glave po meri
• Aktivno stanje

Nove končne točke se začnejo kot aktivne, vsi dogodki, prikazani v urejevalniku, pa so na začetku izbrani. Pred shranjevanjem preverite izbor, da bo prejemnik prejemal samo obvestila, ki jih dejansko potrebuje.

Konfiguriranje URL-ja končne točke

Vnesite celoten javni URL, ki naj prejema zahteve Maildroppe, na primer:

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

URL mora izpolnjevati te zahteve:

• Uporabljati mora https://.
• Vsebovati mora veljavno javno ime gostitelja.
• Dolg je lahko največ 2.048 znakov.
• Ne sme vsebovati spremenljivk predlog z { ali }.
• Pred imenom gostitelja ne sme vsebovati uporabniškega imena ali gesla.
• Ne sme vsebovati fragmenta URL-ja, ki se začne z #.
• Uporabljati mora standardna vrata HTTPS 443.
• Ne sme uporabljati localhost, golega naslova IP ali imena gostitelja, ki se razreši v blokirano zasebno ali rezervirano omrežje.

Parametri poizvedbe so podprti, vendar v URL ne vpisujte ključev API ali drugih skrivnosti. URL-ji so vidni na seznamu končnih točk in v podatkih o dostavah. Za poverilnice raje uporabite glavo po meri.

Maildroppa ne sledi preusmeritvam. Shranite končni cilj HTTPS, ne URL-ja, ki vrača 301, 302, 307 ali 308.

Ime gostitelja cilja se pred pošiljanjem znova razreši. Ime gostitelja, ki se pozneje razreši v zasebni ali blokiran naslov, je zavrnjeno, tudi če je bilo veljavno, ko je bila končna točka shranjena.

Izbira dogodkov

Izberite vsaj en dogodek. Končna točka prejme samo vrste dogodkov, izbrane v njenem urejevalniku.

Stran ponuja te možnosti dogodkov:

Naročnik ustvarjen — subscriber.created

Poslano, ko je v računu Maildroppa ustvarjen naročnik.

Ta dogodek uporabite za ustvarjanje ustreznega stika v sistemu CRM, platformi podatkov o strankah, interni podatkovni zbirki ali drugem sistemu, ki upošteva dovoljenja.

Tega dogodka ne razlagajte kot dokaz, da je vsaka prijava zaključila dvojno potrditev (Double Opt-in). Status naročnika v vsebini opisuje trenutno stanje.

Naročnik posodobljen — subscriber.updated

Poslano, ko se spremenijo vgrajeni podatki naročnika ali vrednosti polj po meri.

Celoten objekt naročnika v vsebini uporabite kot trenutno predstavitev naročnika v Maildroppi. Ne predpostavljajte, da se je spremenila samo določena lastnost.

Dodelitve in odstranitve oznak imajo lastne vrste dogodkov, zato jih je mogoče obravnavati ločeno.

Naročnik odjavljen — subscriber.unsubscribed

Poslano, ko naročnik z dejanjem odjave preide v stanje odjavljen.

Ta dogodek uporabite za izključitev stika v povezanih sistemih. Osebe ne naročite samodejno znova samo zato, ker jo drug sistem še vedno označuje kot aktivno.

Oznaka dodana — subscriber.tag_added

Poslano, ko je naročniku dodeljena oznaka.

Vsebina vsebuje naročnika in oznako, vključeno v to določeno spremembo.

Oznaka odstranjena — subscriber.tag_removed

Poslano, ko je naročniku odstranjena oznaka.

Vsebina vsebuje posodobljenega naročnika in odstranjeno oznako. Odstranjena oznaka je navedena ločeno, čeprav ni več prisotna v trenutnem polju tags naročnika.

Obrazec poslan — form.submitted

Poslano, ko obiskovalec pošlje prijavni obrazec Maildroppa.

To obravnavajte kot signal oddaje obrazca, ne kot potrditev, da je bila dvojna potrditev (Double Opt-in) zaključena. Vsak potek dela, ki zahteva potrjeno naročnino, mora še naprej upoštevati trenutni status naročnika in postopek potrditve.

Ko se odgovornosti razlikujejo, uporabite ločene končne točke

Različne dogodke lahko pošljete različnim sistemom. Na primer:

• Dogodke naročnikov in oznak pošljite v sistem CRM.
• Dogodke odjav pošljite storitvi za izključitve.
• Dogodke oddaje obrazcev pošljite v analitični cevovod.

Ločene končne točke zmanjšajo nepotreben promet in olajšajo diagnosticiranje napak. Vsaka končna točka ima lasten izbor dogodkov, URL, glave po meri, aktivno stanje, preizkuse in zgodovino dostav.

Dodajanje glav po meri

Glave po meri niso obvezne. Uporabite jih, ko prejemnik zahteva ključ API, žeton bearer, identifikator najemnika ali drugo nespremenljivo glavo.

Kliknite »Dodaj glavo«, nato vnesite Ime glave in Vrednost glave. Primerni primeri vključujejo:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Dodate lahko največ 20 glav po meri.

Imena glav:

• So obvezna.
• Vsebujejo lahko največ 128 znakov.
• Uporabljati morajo veljavne znake za imena glav HTTP.
• Biti morajo edinstvena ne glede na velike ali male črke.

Vrednosti glav:

• So obvezne.
• Vsebujejo lahko največ 2.000 znakov.
• Ne smejo vsebovati prelomov vrstic.

Naslednja imena so rezervirana in jih ni mogoče nadomestiti z glavo po meri:

• Content-Type
• Content-Length
• Host
• User-Agent
• Vsako ime, ki se začne z X-Maildroppa-

S tem preprečite, da bi vrednost po meri nadomestila glave Maildroppe za dostavo in podpis.

Kako se shranjujejo skrivnosti v glavah

Maildroppa pred shranjevanjem šifrira vrednosti glav po meri. Shranjene vrednosti brskalniku niso vrnjene v berljivi obliki.

Ko končno točko pozneje urejate, je v polju vrednosti prikazano »Shranjena vrednost ostane«. Pustite ga praznega, če naj obstoječa skrivnost ostane nespremenjena. Vnesite novo vrednost, da jo zamenjate.

Če spremenite ime glave, znova vnesite vrednost. Maildroppa hrani shranjeno skrivnost samo, dokler njeno izvirno ime glave ostane nespremenjeno.

Odstranitev vrstice glave odstrani to glavo iz prihodnjih dostav, ko je končna točka shranjena.

Vrednosti glav po meri se v shranjenih podatkih zahtev obravnavajo kot občutljive. V zgodovini dostav so zakrite in ne prikazane.

Nastavitev končne točke kot aktivne ali neaktivne

Pustite izbrano možnost »Aktivno«, ko je končna točka pripravljena na takojšnje prejemanje dogodkov.

Počistite jo, ko želite shraniti konfiguracijo, ne da bi začeli dostave. Končno točko lahko pozneje aktivirate na seznamu končnih točk.

Neaktivna končna točka:

• Ne prejema novo nastalih dogodkov.
• Ne more poslati preizkusa spletnega kavlja.
• Ostane vidna in jo je mogoče urejati.
• Ohrani dostop do obstoječe zgodovine dostav.

Aktivacija končne točke ne zapolni za nazaj dogodkov, ki so se zgodili, ko je bila neaktivna.

Ko so URL, izbor dogodkov, glave in stanje pravilni, kliknite »Shrani«.

Razumevanje seznama končnih točk

Vsaka vrstica končne točke prikazuje:

• Ciljni URL.
• Značko Aktivno ali Neaktivno.
• Naročene vrste dogodkov.
• Število glav po meri.
• Čas zadnje posodobitve končne točke.

Na voljo so ta dejanja:

• Vklop/izklop — Aktivira ali deaktivira končno točko.
• Preizkus — Pošlje eno takojšnjo preizkusno zahtevo aktivni končni točki.
• Uredi — Spremeni URL, dogodke, glave ali aktivno stanje.
• Izbriši — Po potrditvi trajno odstrani konfiguracijo končne točke.

Izberite glavni del vrstice, da odprete zgodovino dostav te končne točke pod seznamom.

Kako shranjene spremembe vplivajo na obstoječe dostave

Dogodek računa ustvari dostavo s posnetkom URL-ja končne točke, vsebine in glav po meri v tistem trenutku.

Urejanje URL-ja ali glav po meri vpliva na na novo ustvarjene dostave. Dostava, ki je že v čakalni vrsti, ohrani izvirni cilj in shranjeno konfiguracijo glav.

Sprememba izbranih dogodkov prav tako vpliva samo na dogodke, ki se zgodijo pozneje. Maildroppa ne ustvarja retroaktivnih dostav za vrste dogodkov, ki niso bile izbrane, ko se je dogodek zgodil.

Skrivnost za podpisovanje je drugačna: prebere se, ko je zahteva HTTP pripravljena. Čakajoča dostava ali ponovna predvajanja lahko zato uporabijo novo zavrteno skrivnost, tudi če sta bila njena vsebina in posnetek končne točke ustvarjena prej.

Preizkušanje končne točke

Ko so prejemnik in skrivnost za podpisovanje pripravljeni, kliknite »Preizkus« pri aktivni končni točki.

Maildroppa takoj pošlje eno podpisano zahtevo z uporabo shranjenega URL-ja končne točke in shranjenih glav po meri. Neshranjene spremembe v odprtem urejevalniku niso del preizkusa.

Vsebina preizkusa uporablja vrsto dogodka webhook.test in nastavi 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."
  }
}

Ustvarjeni ID-ji in časovni žig se pri vsakem pravem preizkusu razlikujejo.

Preizkus izvede natanko en poskus HTTP. Preizkusne dostave niso vključene v produkcijski urnik ponovnih poskusov in jih ni mogoče znova predvajati.

Ko se zahteva konča, plošča z rezultatom prikaže:

• Preizkus uspešen ali Preizkus neuspešen
• ID dogodka
• Status HTTP, če je bil prejet odgovor
• Trajanje
• ID dostave
• Podatke o napaki, če so na voljo
• Izsek odgovora, če je prejemnik vrnil telo

Preizkus se prikaže tudi v zgodovini dostav z značko Preizkus. S filtrom »Preizkus« prikažete samo preizkusne zahteve.

Razumevanje produkcijske vsebine

Produkcijski dogodki računa uporabljajo skupno ovojnico JSON:

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

Lastnosti na najvišji ravni pomenijo:

• id — ID dogodka. Ujema se z X-Maildroppa-Event-Id.
• type — Ključ dogodka, izbran v urejevalniku končne točke.
• schema_version — Različica sheme vsebine. Uporabite jo pri odločanju, kako razčleniti dogodek.
• created_at — Čas ustvarjanja vsebine dogodka v UTC.
• livemode — true za produkcijske dogodke in false za preizkusne dogodke.
• data — Vsebina, značilna za dogodek.

Dogodke usmerjajte po natančni vrednosti type. Dodatne lastnosti, ki jih vaša integracija ne potrebuje, prezrite, da združljive dopolnitve vsebine ne bodo prekinile prejemnika.

Vsebina dogodkov naročnika

Dogodki naročnika vsebujejo trenutno predstavitev naročnika znotraj 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 in tags sta polji. Lahko sta prazni. Lastnost naročnika je lahko tudi null, kadar vrednost ne obstaja, zato naj vaš prejemnik sledi shemi vsebine, namesto da predpostavlja prisotnost vsake neobvezne profilne vrednosti.

Vsebina dogodkov oznak

Dogodki oznak vsebujejo naročnika in oznako, ki je povzročila dogodek:

{
  "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 data.tag še vedno določa odstranjeno oznako, čeprav je trenutna tabela tags naročnika ne vsebuje več.

ID-ji dogodkov, ID-ji dostav in idempotentnost

ID dogodka in ID dostave imata različna namena.

ID dogodka

ID dogodka določa poslovni dogodek. Pojavlja se v:

• Lastnosti id na najvišji ravni vsebine.
• Glavi zahteve X-Maildroppa-Event-Id.
• Zgodovini dostav.

Isti dogodek je lahko poslan več naročenim končnim točkam. Te dostave imajo skupni ID dogodka.

Ponovni poskusi in ročna ponovna predvajanja prav tako ohranijo izvirni ID dogodka. Shranjujte obdelane ID-je dogodkov in poslovno dejanje naredite idempotentno, da ponovljena zahteva ne ustvari podvojenih stikov, ne ponovi nepovratnega dejanja ali dvakrat uporabi iste spremembe.

ID dostave

ID dostave določa en zapis dostave. Pojavlja se v:

• Glavi zahteve X-Maildroppa-Delivery-Id.
• Zgodovini dostav.

Vsaka dostava končni točki ima svoj ID dostave. Ročno ponovno predvajanje ustvari nov ID dostave, pri tem pa ohrani izvirni ID dogodka.

ID dostave uporabite za tehnično sledenje in podporo. ID dogodka uporabite za deduplikacijo na poslovni ravni.

Vračanje pravilnega odgovora HTTP

Maildroppa odgovore razvršča tako:

• Vsak odgovor 2xx označi dostavo kot uspešno.
• Odgovori 408 Request Timeout, 429 Too Many Requests in 5xx so začasne napake, pri katerih je mogoče poskus ponoviti.
• Omrežne napake, ki so lahko začasne, se znova poskusijo.
• Preusmeritve in drugi odgovori 3xx se ne upoštevajo in obravnavajo kot končne napake.
• Drugi odgovori 4xx se obravnavajo kot končne napake in se ne ponovijo.

200, 202 ali 204 vrnite samo, ko je bil dogodek varno sprejet. Če obdelava traja, dogodek najprej shranite in vrnite uspešen odgovor, nato pa počasnejše delo izvedite asinhrono.

Ne vračajte preusmeritve na drug URL spletnega kavlja. Končni URL konfigurirajte neposredno v Maildroppi.

Samodejni urnik ponovnih poskusov

Produkcijske dostave lahko izvedejo največ sedem poskusov HTTP.

Po napaki, pri kateri je mogoče poskus ponoviti, Maildroppa načrtuje naslednji poskus s temi zamiki:

1. Po 1. poskusu: 1 minuta
2. Po 2. poskusu: 5 minut
3. Po 3. poskusu: 30 minut
4. Po 4. poskusu: 2 uri
5. Po 5. poskusu: 12 ur
6. Po 6. poskusu: 24 ur

Če je pri 7. poskusu še vedno prejeta napaka, pri kateri je mogoče poskus ponoviti, dostava postane mrtva in nadaljnji samodejni poskus ni načrtovan.

Urnik se meri od posameznih neuspešnih poskusov. Dejanski čas dostave je lahko nekoliko poznejši, ker se dostave obdelujejo asinhrono in zanje veljajo tudi omejitve sistemske zaščite.

Začasno težavo pri prejemniku odpravite pred prikazanim časom »Naslednji ponovni poskus«, kadar je to mogoče. Če so se samodejni poskusi končali, uporabite Ponovno predvajaj, ko je prejemnik spet zdrav.

Razumevanje zgodovine dostav

Zgodovina dostav pripada trenutno izbrani končni točki. URL končne točke se prikaže v glavi razdelka, da lahko potrdite, katero zgodovino si ogledujete.

Uporabite te filtre:

• Vse — Prikaže produkcijske in preizkusne dostave.
• Produkcija — Prikaže samo dostave živih dogodkov.
• Preizkus — Prikaže samo ročne preizkuse.

Kliknite »Osveži«, da pridobite najnovejše stanje. Zgodovine ni treba pustiti odprte, medtem ko Maildroppa pošilja dostavo ali znova poskuša.

Stran prikaže zadnjih 50 ujemajočih se dostav za izbrani filter.

Stolpci dostav

Vsaka vrstica vsebuje:

• Ustvarjeno — Kdaj je bil ustvarjen zapis dostave.
• Stanje — Čakajoče, Uspešno, Neuspešno ali Mrtvo.
• HTTP — Status odgovora, število poskusov, trajanje in čas naslednjega ponovnega poskusa, kadar je ustrezno.
• Naročnik — E-pošta naročnika, ko je dogodek povezan z naročnikom.
• Dostava — Vrsta dogodka, ID dogodka in ID dostave.
• Dejanja — Ponovno predvajaj, ko je dostava primerna.

Če zahteva HTTP ni bila izvedena, stolpec HTTP prikazuje »Ni poskusa HTTP«. To se lahko zgodi, ko Maildroppa zahtevo zavrne pred pošiljanjem, na primer ker manjka skrivnost za podpisovanje ali shranjenega cilja ni več mogoče varno uporabiti.

Kadar je na voljo, vrstica prikaže tudi Napako in Izsek odgovora, ki ga je vrnil prejemnik. V odgovor telesa spletnega kavlja ne vračajte skrivnosti ali občutljivih osebnih podatkov, saj se lahko del tega odgovora prikaže v dnevniku dostav računa.

Stanja dostav

Čakajoče pomeni, da dostava čaka na prvi poskus ali načrtovani ponovni poskus. »Naslednji ponovni poskus« se prikaže, ko je načrtovan nov poskus.

Uspešno pomeni, da je prejemnik vrnil odgovor 2xx. Nadaljnji samodejni poskus ni potreben.

Neuspešno pomeni, da se je dostava končala z napako, pri kateri ponovni poskus ni mogoč, je bila zavrnjena pred poskusom HTTP ali ustavljena, preden jo je bilo mogoče poslati.

Mrtvo pomeni, da so bili pri napaki, pri kateri je mogoče poskus ponoviti, porabljeni vsi samodejni poskusi, ne da bi bil prejet uspešen odgovor.

Hramba zgodovine

Zapisi dostav se hranijo omejen čas:

• Uspešne produkcijske dostave: 30 dni
• Neuspešne produkcijske dostave: 90 dni
• Mrtve produkcijske dostave: 90 dni
• Preizkusne dostave: 30 dni

Ko potrebujete daljšo revizijsko zgodovino, hranite lastne dnevnike integracije. Shranjujte ID-je dogodkov in ID-je dostav, vendar se izogibajte nepotrebnemu shranjevanju skrivnosti.

Ponovno predvajanje dostave

Kliknite »Ponovno predvajaj«, ko je treba dokončano produkcijsko dostavo poskusiti znova.

Ponovno predvajanje je na voljo za produkcijske dostave v stanju Uspešno, Neuspešno ali Mrtvo. Medtem ko je dostava Čakajoča, ni na voljo, preizkusnih dostav pa ni mogoče znova predvajati.

Ponovno predvajanje:

• Ustvari novo čakajočo dostavo.
• Ustvari nov ID dostave.
• Ohrani izvirni ID dogodka.
• Ohrani izvirno vrsto dogodka in vsebino JSON.
• Uporabi izvirni shranjeni ciljni URL in posnetek glav po meri.
• Uporabi trenutno skrivnost za podpisovanje, ko je nova zahteva pripravljena.

Ponovno predvajanje ne sestavi vsebine na novo iz trenutnih podatkov naročnika. Znova pošlje izvirni posnetek dogodka. Tako je ponovno predvajanje mogoče revidirati in prepreči, da bi zgodovinski dogodek neopazno spremenil pomen.

Hkrati je lahko čakajoče samo eno ponovno predvajanje iste izvorne dostave. Preden zahtevate novo, počakajte, da se to ponovno predvajanje konča.

Pred ponovnim predvajanjem preverite, ali je končna točka aktivna. Če je neaktivna, čakajočega ponovnega predvajanja ni mogoče uspešno dostaviti.

Ker je prejemnik morda izvedel poslovno dejanje, tudi če Maildroppa ni prejela njegovega uspešnega odgovora, lahko ponovno predvajanje ustvari podvojeno zahtevo. Deduplikacija po ID-ju dogodka povezani sistem zaščiti pred ponovitvijo dejanja.

Urejanje končne točke

Kliknite »Uredi«, da spremenite URL, izbor dogodkov, glave po meri ali aktivno stanje.

Pred shranjevanjem:

1. Potrdite, da je novi URL že na voljo.
2. Shranjene vrednosti glav pustite prazne, kadar naj ostanejo nespremenjene.
3. Vnesite novo vrednost za vsako preimenovano glavo.
4. Preglejte izbor dogodkov, da zahtevanih obvestil ne odstranite po pomoti.
5. Shranite in pošljite nov preizkus spletnega kavlja.

Ne pozabite, da čakajoče dostave ohranijo obstoječi URL in posnetek glav po meri. Novo konfiguracijo preizkusite za prihodnje dostave, namesto da bi predpostavljali, da spremeni starejšo čakajočo zahtevo.

Deaktiviranje končne točke

Uporabite stikalo Vklop/izklop, ko želite začasno ustaviti integracijo, ne da bi izbrisali njeno konfiguracijo in zgodovino.

Ko je končna točka izklopljena:

• Novi dogodki zanjo niso več uvrščeni v čakalno vrsto.
• Čakajoče dostave, ki še niso bile prevzete za pošiljanje, so označene kot neuspešne.
• Preizkus je onemogočen.
• Končna točka ostane na voljo za urejanje in poznejšo aktivacijo.

Zahteva, ki je bila ob deaktivaciji že v teku, se lahko še vedno konča. Če je ta razlika pomembna za vašo integracijo, po izklopu končne točke preverite zgodovino dostav.

Dogodki, ki so bili zamujeni, ko je bila končna točka neaktivna, se ob ponovnem vklopu ne zapolnijo za nazaj.

Brisanje končne točke

Ko končna točka ne sme več obstajati, kliknite »Izbriši« in potrdite opozorilo.

Brisanje odstrani končno točko s strani, ustavi prihodnje dostave dogodkov in označi čakajoče dostave, ki še niso bile prevzete za pošiljanje, kot neuspešne.

Brisanje ni način za začasno zaustavitev. Uporabite stikalo Vklop/izklop, ko boste morda znova potrebovali konfiguracijo ali vidno zgodovino.

Pred brisanjem si zabeležite vse ID-je dogodkov ali ID-je dostav, ki jih še potrebujete za revizijo integracije.

Odpravljanje težav

Končne točke ni mogoče shraniti

Preverite, ali:

• Se URL začne z https://.
• URL uporablja javno ime gostitelja in vrata 443.
• URL ne vsebuje spremenljivk, prijavnih podatkov ali fragmenta.
• Je izbran vsaj en dogodek.
• Ima vsaka glava po meri edinstveno ime in vrednost.
• Rezervirana Maildroppina in glave HTTP niso uporabljene kot imena po meri.

Preizkus je onemogočen

Preizkus je na voljo samo za aktivno končno točko. Končno točko vklopite ali jo uredite in izberite »Aktivno«, nato pa jo pred preizkusom shranite.

Preizkus ne prikaže poskusa HTTP

Če je stanje Manjka, ustvarite skrivnost za podpisovanje. Preverite tudi, ali je ciljno ime gostitelja javno in se še vedno pravilno razrešuje.

Zahteva je lahko zavrnjena pred pošiljanjem, če so njena skrivnost, URL, glave po meri ali preverjanje varnosti cilja neveljavni.

Prejemnik vrne 401 ali 403

Preverite shranjeno ime glave po meri in poverilnico. Če se je spremenila, uredite končno točko in znova vnesite vrednost.

Preverite tudi, ali prejemnik svoje poverilnice API ne zamenjuje s podpisom Maildroppe. Glava za pooblastilo po meri in X-Maildroppa-Signature služita različnima namenoma in ju je mogoče preverjati neodvisno.

Prejemnik vrne preusmeritev

Maildroppa ne sledi preusmeritvam. URL končne točke zamenjajte s končnim javnim URL-jem HTTPS in znova izvedite preizkus.

Podpis se ne ujema

Potrdite, da prejemnik:

• Uporablja trenutno skrivnost za podpisovanje.
• Uporablja natančno vrednost X-Maildroppa-Timestamp.
• Podpiše <timestamp>.<raw request body>.
• Uporablja HMAC-SHA256 in male šestnajstiške znake.
• Primerja celotno vrednost, vključno z v1=.
• Primerjavo izvede, preden razčlenjevanje JSON spremeni telo.

Isti dogodek prispe več kot enkrat

To se lahko zgodi po prekinitvi omrežja, ponovnem poskusu ali ročnem ponovnem predvajanju. Za sisteme dostave spletnih kavljev je običajno, da zagotavljajo dostavo vsaj enkrat, ne pa natanko enkrat.

ID dogodka uporabite kot idempotentni ključ. Ko je že obdelan ID dogodka prejet znova in dodatno dejanje ni potrebno, vrnite odgovor 2xx.

Dostava čaka

V stolpcu HTTP preverite »Naslednji ponovni poskus«. Ponovljiva napaka 408, 429, 5xx ali začasna omrežna napaka ostane v stanju Čakajoče do naslednjega načrtovanega poskusa.

Po času ponovnega poskusa kliknite »Osveži«, da naložite najnovejše stanje.

Dostava je mrtva

Vsi samodejni poskusi so bili porabljeni. Najprej popravite prejemnika, preverite, ali je končna točka aktivna, pošljite preizkus spletnega kavlja in nato pri produkcijski dostavi uporabite Ponovno predvajaj.

Priporočeni produkcijski kontrolni seznam

Preden se na končno točko zanesete v produkciji, potrdite vse naslednje:

1. Prejemnik uporablja stabilen javni URL HTTPS z veljavnim potrdilom.
2. Skrivnost za podpisovanje je shranjena zunaj izvorne kode.
3. Podpis se preverja glede na nespremenjeno neobdelano telo.
4. Stari časovni žigi so zavrnjeni v skladu z dokumentirano toleranco.
5. Prejemnik shranjuje in deduplicira ID-je dogodkov.
6. Prejemnik za sledenje beleži ID-je dogodkov in ID-je dostav.
7. Počasna obdelava poteka po trajnem sprejemu dogodka.
8. Odgovor 2xx se vrne samo za sprejete dogodke.
9. Poverilnice po meri so shranjene v glavah, ne v URL-ju.
10. Izbrane so samo zahtevane vrste dogodkov.
11. Preizkus spletnega kavlja je uspešen in se pravilno prikaže v zgodovini dostav.
12. Spremljanje vas opozori, ko produkcijske dostave začnejo vračati napake.

S temi zaščitnimi ukrepi stran Spletni kavlji zagotavlja oba vidika zanesljive integracije: varno dostavo dogodkov vaši aplikaciji in pregleden operativni zapis v Maildroppi.