Konfigūruoti Webhooks

Published: 2026 m. liepos 16 d. · Last updated: 2026 m. liepos 21 d. · By Marcus Biel

Webhooks leidžia Maildroppa pranešti kitai programai, kai jūsų paskyroje įvyksta kas nors svarbaus.

Užuot pakartotinai klaususi Maildroppa, ar prenumeratorius buvo sukurtas, atnaujintas, atsisakė prenumeratos ar jam priskirta žyma, jūsų programa gali gauti HTTPS užklausą netrukus po įvykio.

Webhooks puslapis yra pagrindinė vieta šiai visos paskyros integracijai valdyti. Čia galite sukurti kelis galinius taškus, pasirinkti, kuriuos įvykius gauna kiekvienas galinis taškas, pridėti autentifikavimo antraštes, išbandyti ryšį, peržiūrėti pristatymo bandymus ir prireikus pakartoti gamybinį įvykį.

Kaip veikia paskyros Webhooks

Paskyros webhook veikia taip:

1. Maildroppa įvyksta įvykis, pavyzdžiui, sukuriamas prenumeratorius.
2. Maildroppa randa kiekvieną aktyvų galinį tašką, užsiprenumeravusį šį įvykį.
3. Maildroppa sukuria po vieną pristatymą kiekvienam atitinkančiam galiniam taškui.
4. JSON naudingoji apkrova pasirašoma jūsų paskyros webhook Signing secret.
5. Maildroppa siunčia HTTPS POST užklausą išsaugotu galinio taško URL.
6. Jūsų galinis taškas patikrina parašą, išsaugo arba apdoroja įvykį ir grąžina HTTP atsakymą.
7. Maildroppa įrašo rezultatą į Delivery history ir automatiškai pakartoja laikinų klaidų atveju.

Jei keli galiniai taškai užsiprenumeruoja tą patį įvykį, kiekvienas galinis taškas gauna atskirą pristatymą. Verslo įvykio Event ID visiems pristatymams yra vienodas, o kiekvienas pristatymas turi savo Delivery ID.

Paskyros webhooks skiriasi nuo „Send a webhook“ veiksmo Automation viduje. Paskyros webhooks stebi pasirinktus paskyros įvykius visoje Maildroppa sistemoje. Automation webhook siunčiamas tik tada, kai prenumeratorius pasiekia konkretų veiksmą. Abu naudoja paskyros webhook Signing secret, todėl paslapties pakeitimas turi įtakos kiekvienam siunčiamų webhook gavėjui, tikrinančiam Maildroppa parašus.

Webhooks puslapio atidarymas

Atidarykite „Settings“, išskleiskite „Developers“ ir pasirinkite „Webhooks“.

Puslapį sudaro trys pagrindinės sritys:

• Signing secret
• Endpoints
• Pasirinkto galinio taško Delivery history

Kai turite daugiau nei vieną galinį tašką, pasirinkite galinio taško eilutę, kad būtų rodoma jo Delivery history. Jei aiškiai nepasirinkote galinio taško, Maildroppa rodo pirmojo sąraše esančio galinio taško istoriją.

Prieš kuriant galinį tašką

Prieš konfigūruodami Maildroppa, paruoškite gavėją savo serveryje. Gavėjas turėtų:

• Būti pasiekiamas viešu HTTPS URL.
• Priimti POST užklausas su application/json turiniu.
• Išsaugoti neapdorotą užklausos turinį, kol bus patikrintas Maildroppa parašas.
• Grąžinti 2xx būseną tik tada, kai įvykis saugiai priimtas.
• Apdoroti pakartotinius pristatymus idempotentiškai, naudojant Event ID.
• Atsakyti greitai, užuot atliekant lėtus veiksmus užklausos metu.

Patikimas būdas – patikrinti užklausą, išsaugoti Event ID ir naudingąją apkrovą patvarioje eilėje arba duomenų bazėje, grąžinti 200 arba 204, o verslo veiksmą atlikti vėliau.

Neatskleiskite kūrimo kompiuterio, vietinio tinklo adreso ar neapsaugoto scenarijaus kaip gamybinio webhook gavėjo. Maildroppa priima tik viešus HTTPS adresatus ir dar kartą patikrina paskirties vietą siųsdama pristatymą.

1 veiksmas: sugeneruokite Signing secret

Kiekviena Maildroppa webhook užklausa pasirašoma. Jūsų gavėjas naudoja Signing secret, kad patikrintų, jog užklausą sukūrė Maildroppa ir kad jos turinys nebuvo pakeistas perduodant.

Puslapio viršuje Signing secret skydelyje rodoma viena iš šių būsenų:

• Missing — Signing secret dar nėra.
• Ready — Signing secret sukonfigūruotas.
• Loading — Maildroppa gauna dabartinę būseną.

Kai būsena yra Missing, spustelėkite „Generate secret“.

Maildroppa iš karto parodo naują paslaptį. Ji prasideda whsec_. Spustelėkite „Copy“ ir išsaugokite ją paslapčių tvarkytuvėje arba apsaugotoje aplinkos konfigūracijoje, kurią naudoja jūsų gavėjas.

Visa reikšmė rodoma tik iš karto po sugeneravimo arba pakeitimo. Perkrovus puslapį ar išėjus iš jo, Maildroppa rodo tik tai, kad paslaptis egzistuoja, ir kada ji paskutinį kartą atnaujinta. Išsaugotos paslapties dar kartą neatskleidžia.

Jei praradote paslaptį

Jei gavėjas nebeturi dabartinės paslapties, spustelėkite „Rotate secret“ ir išsaugokite naujai parodytą reikšmę.

Pakeitus paslaptį, ankstesnė paslaptis iš karto pakeičiama. Maildroppa nelaiko abiejų reikšmių pereinamuoju laikotarpiu. Prieš siųsdami tolesnius bandymus ar pasikliaudami gamybiniais pristatymais, atnaujinkite kiekvieną gavėją, naudojantį šią paskyros paslaptį.

Nauji pristatymai, suplanuoti pakartotiniai bandymai, testai ir pakartojimai pasirašomi dabartine paslaptimi tuo metu, kai siunčiama HTTP užklausa. Tai reiškia, kad prieš paslapties pakeitimą sukurtas pristatymas vėliau bandant jį išsiųsti vis tiek gali būti pasirašytas nauja paslaptimi.

Elkitės su paslaptimi kaip su slaptažodžiu

Nedėkite Signing secret į naršyklės kodą, viešą saugyklą, URL, klaidos puslapį ar įprastą programos žurnalą.

Paslapties reikia tik serverio pusėje veikiančiam gavėjui. Jei manote, kad ji buvo atskleista, nedelsdami pakeiskite ją ir atnaujinkite visus gavėjus.

Webhook parašo tikrinimas

Kiekvienoje užklausoje pateikiamos šios Maildroppa antraštės:

• X-Maildroppa-Event-Id — Identifikuoja verslo įvykį.
• X-Maildroppa-Delivery-Id — Identifikuoja konkretų pristatymą.
• X-Maildroppa-Timestamp — Pasirašymo laikas Unix sekundėmis.
• X-Maildroppa-Signature — Versijuotas HMAC parašas.

Maildroppa taip pat siunčia:

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

Parašo formatas:

v1=<lowercase hexadecimal HMAC>

Maildroppa jį sukuria naudodama HMAC-SHA256. Pasirašomas turinys yra laiko žyma, po jos einantis taškas ir tikslus neapdorotas JSON užklausos turinys:

<timestamp>.<raw request body>

Kaip HMAC raktą naudokite Signing secret.

Toliau pateiktame Node.js pavyzdyje parodytas esminis tikrinimo veiksmas. rawBody turi būti originalūs užklausos baitai, o ne JSON, kuris jau buvo išanalizuotas ir dar kartą suserializuotas.

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

Patikrinę parašą, taip pat palyginkite laiko žymą su serverio laiku. Atmeskite užklausas, kurių laikas nepatenka į jūsų infrastruktūrai pasirinktą trumpą tolerancijos intervalą, pavyzdžiui, penkias minutes. Tai sumažina riziką, kad užfiksuota tinkama užklausa bus pakartota daug vėliau.

JSON analizuokite ir apdorokite tik tada, kai abu patikrinimai sėkmingi.

Dažniausios parašo klaidų priežastys

Parašas dažniausiai nepavyksta dėl vienos iš šių priežasčių:

• Pakeitus paslaptį gavėjas naudoja seną paslaptį.
• Tarpinė programinė įranga išanalizavo arba pakeitė JSON prieš apskaičiuojant parašą.
• Gavėjas pasirašo tik turinį ir praleidžia <timestamp>..
• Laiko žyma laikoma suformatuota data, o ne tikslia antraštės reikšme.
• Palyginant praleidžiamas v1= prefiksas.
• Apskaičiuotas HMAC užkoduojamas kitaip, o ne mažosiomis šešioliktainėmis raidėmis.

Kai tikrinimas nepavyksta, registruokite Event ID ir Delivery ID, bet niekada neregistruokite Signing secret ar jautrių pasirinktinių antraščių reikšmių.

2 veiksmas: pridėkite galinį tašką

Endpoints skiltyje spustelėkite „Add endpoint“.

Redaktorių sudaro keturios dalys:

• Endpoint URL
• Events
• Custom headers
• Active status

Nauji galiniai taškai pradeda veikti kaip Active, o visi redaktoriuje rodomi įvykiai iš pradžių būna pasirinkti. Prieš išsaugodami peržiūrėkite pasirinkimą, kad gavėjas gautų tik tuos pranešimus, kurių jam iš tikrųjų reikia.

Galinio taško URL konfigūravimas

Įveskite visą viešą URL, kuriuo turėtų būti priimamos Maildroppa užklausos, pavyzdžiui:

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

URL turi atitikti šiuos reikalavimus:

• Turi naudoti https://.
• Turi būti galiojantis viešas pagrindinio kompiuterio vardas.
• Gali būti ne ilgesnis kaip 2 048 simboliai.
• Negali būti šablono kintamųjų su { arba }.
• Prieš pagrindinio kompiuterio vardą negali būti vartotojo vardo ar slaptažodžio.
• Negali būti URL fragmento, prasidedančio #.
• Turi naudoti standartinį HTTPS prievadą 443.
• Negali naudoti localhost, neapdoroto IP adreso ar pagrindinio kompiuterio vardo, kuris nukreipiamas į užblokuotą privatų ar rezervuotą tinklą.

Užklausos parametrai palaikomi, tačiau nedėkite API raktų ar kitų paslapčių į URL. URL matomi galinių taškų sąraše ir pristatymo duomenyse. Kredencialams naudokite Custom header.

Maildroppa neseka peradresavimų. Išsaugokite galutinę HTTPS paskirties vietą, o ne URL, grąžinantį 301, 302, 307 ar 308.

Prieš siunčiant paskirties pagrindinio kompiuterio vardas išsprendžiamas dar kartą. Pagrindinio kompiuterio vardas, vėliau nukreipiamas į privatų ar užblokuotą adresą, atmetamas, net jei išsaugant galinį tašką jis buvo tinkamas.

Įvykių pasirinkimas

Pasirinkite bent vieną įvykį. Galinis taškas gauna tik tuos įvykių tipus, kurie pasirinkti jo redaktoriuje.

Puslapyje siūlomi šie įvykiai:

Subscriber Created — subscriber.created

Siunčiamas, kai Maildroppa paskyroje sukuriamas prenumeratorius.

Naudokite šį įvykį, kad sukurtumėte atitinkamą kontaktą CRM, klientų duomenų platformoje, vidinėje duomenų bazėje ar kitoje leidimus atsižvelgiančioje sistemoje.

Nelaikykite šio įvykio įrodymu, kad kiekvienas užsiregistravęs asmuo užbaigė Double Opt-in. Prenumeratoriaus būsena naudingojoje apkrovoje apibūdina dabartinę būseną.

Subscriber Updated — subscriber.updated

Siunčiamas, kai pasikeičia pagrindinė prenumeratoriaus informacija arba pasirinktinių laukų reikšmės.

Naudokite visą prenumeratoriaus objektą naudingojoje apkrovoje kaip dabartinį Maildroppa atvaizdą. Nemanykite, kad pasikeitė tik viena konkreti ypatybė.

Žymų priskyrimai ir pašalinimai turi atskirus įvykių tipus, todėl juos galima apdoroti atskirai.

Subscriber Unsubscribed — subscriber.unsubscribed

Siunčiamas, kai prenumeratorius, atlikus atsisakymo veiksmą, pereina į atsisakiusio prenumeratos būseną.

Naudokite šį įvykį, kad prijungtose sistemose kontaktui būtų taikomas slopinimas. Automatiškai iš naujo neužprenumeruokite asmens vien todėl, kad kita sistema vis dar žymi kontaktą kaip aktyvų.

Tag Added — subscriber.tag_added

Siunčiamas, kai prenumeratoriui priskiriama žyma.

Naudingojoje apkrovoje pateikiamas prenumeratorius ir su konkrečiu pakeitimu susijusi žyma.

Tag Removed — subscriber.tag_removed

Siunčiamas, kai žyma pašalinama iš prenumeratoriaus.

Naudingojoje apkrovoje pateikiamas atnaujintas prenumeratorius ir pašalinta žyma. Pašalinta žyma pateikiama atskirai, nors jos nebėra dabartiniame prenumeratoriaus tags masyve.

Form Submitted — form.submitted

Siunčiamas, kai lankytojas pateikia Maildroppa registracijos formą.

Laikykite tai formos pateikimo signalu, o ne patvirtinimu, kad Double Opt-in užbaigtas. Bet kokia darbo eiga, kuriai reikalinga patvirtinta prenumerata, turi ir toliau atsižvelgti į dabartinę prenumeratoriaus būseną ir patvirtinimo procesą.

Kai atsakomybės skiriasi, naudokite atskirus galinius taškus

Skirtingoms sistemoms galite siųsti skirtingus įvykius. Pavyzdžiui:

• Prenumeratoriaus ir žymų įvykius siųskite į CRM.
• Atsisakymo prenumeratos įvykius siųskite į slopinimo paslaugą.
• Formos pateikimo įvykius siųskite į analizės konvejerį.

Atskiri galiniai taškai sumažina nereikalingą srautą ir palengvina klaidų diagnozavimą. Kiekvienas galinis taškas turi savo įvykių pasirinkimą, URL, pasirinktines antraštes, aktyvią būseną, testus ir Delivery history.

Pasirinktinių antraščių pridėjimas

Pasirinktinės antraštės nėra privalomos. Naudokite jas, kai gavėjui reikia API rakto, bearer žetono, nuomininko identifikatoriaus ar kitos nekintamos antraštės.

Spustelėkite „Add header“, tada įveskite Header name ir Header value. Tinkami pavyzdžiai:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Galite pridėti iki 20 pasirinktinių antraščių.

Antraščių pavadinimai:

• Yra privalomi.
• Gali būti iki 128 simbolių ilgio.
• Turi naudoti tinkamus HTTP antraštės pavadinimo simbolius.
• Turi būti unikalūs, neatsižvelgiant į didžiąsias ir mažąsias raides.

Antraščių reikšmės:

• Yra privalomos.
• Gali būti iki 2 000 simbolių ilgio.
• Negali turėti eilučių lūžių.

Šie pavadinimai yra rezervuoti ir jų negalima pakeisti pasirinktine antrašte:

• Content-Type
• Content-Length
• Host
• User-Agent
• Bet kuris pavadinimas, prasidedantis X-Maildroppa-

Taip neleidžiama pasirinktinei reikšmei pakeisti Maildroppa pristatymo ir parašo antraščių.

Kaip saugomos antraščių paslaptys

Maildroppa užšifruoja pasirinktinių antraščių reikšmes prieš jas išsaugodama. Išsaugotos reikšmės į naršyklę negrąžinamos perskaitomu pavidalu.

Vėliau redaguojant galinį tašką, reikšmės lauke rodoma „Stored value kept“. Palikite jį tuščią, jei esama paslaptis turi likti nepakeista. Įveskite naują reikšmę, kad ją pakeistumėte.

Jei pakeičiate antraštės pavadinimą, reikšmę įveskite dar kartą. Maildroppa išsaugotą paslaptį išlaiko tik tol, kol jos pradinis antraštės pavadinimas nesikeičia.

Pašalinus antraštės eilutę, ši antraštė pašalinama iš būsimų pristatymų, kai galinis taškas išsaugomas.

Pasirinktinių antraščių reikšmės saugomuose užklausų duomenyse laikomos jautriomis. Delivery history jos užmaskuojamos, o ne rodomos.

Galinio taško aktyvios arba neaktyvios būsenos nustatymas

Palikite „Active“ pasirinktą, kai galinis taškas pasiruošęs iš karto gauti įvykius.

Panaikinkite pasirinkimą, kai norite išsaugoti konfigūraciją nepradėdami pristatymų. Galinį tašką vėliau galite aktyvinti galinių taškų sąraše.

Neaktyvus galinis taškas:

• Neima naujai įvykstančių įvykių.
• Negali siųsti Test webhook.
• Lieka matomas ir redaguojamas.
• Išlaiko prieinamą esamą Delivery history.

Aktyvinus galinį tašką, įvykiai, įvykę jam esant neaktyviam, nepapildomi atgaline data.

Spustelėkite „Save“, kai URL, įvykių pasirinkimas, antraštės ir būsena yra teisingi.

Galinio taško sąrašo supratimas

Kiekvienoje galinio taško eilutėje rodoma:

• Paskirties URL.
• Active arba Inactive ženklelis.
• Užprenumeruoti įvykių tipai.
• Pasirinktinių antraščių skaičius.
• Laikas, kada galinis taškas paskutinį kartą atnaujintas.

Galimi veiksmai:

• On/Off — Aktyvina arba išaktyvina galinį tašką.
• Test — Iš karto siunčia vieną testinę užklausą aktyviam galiniam taškui.
• Edit — Pakeičia URL, įvykius, antraštes arba aktyvią būseną.
• Delete — Po patvirtinimo visam laikui pašalina galinio taško konfigūraciją.

Pasirinkite pagrindinę eilutės dalį, kad po sąrašu atidarytumėte šio galinio taško Delivery history.

Kaip išsaugoti pakeitimai veikia esamus pristatymus

Paskyros įvykis sukuria pristatymą su tuo metu užfiksuotu galinio taško URL, naudinga apkrova ir pasirinktinėmis antraštėmis.

URL arba pasirinktinių antraščių redagavimas turi įtakos naujai sukurtiems pristatymams. Jau eilėje esantis pristatymas išlaiko pradinę paskirties vietą ir išsaugotą antraščių konfigūraciją.

Pasirinktų įvykių pakeitimas taip pat turi įtakos tik vėliau įvykstantiems įvykiams. Maildroppa retrospektyviai nekuria pristatymų įvykių tipams, kurie nebuvo pasirinkti įvykio metu.

Signing secret skiriasi: jis nuskaitomas ruošiant HTTP užklausą. Todėl laukiantis pristatymas arba pakartojimas gali naudoti naujai pakeistą Signing secret, net jei jo naudingoji apkrova ir galinio taško momentinė kopija buvo sukurti anksčiau.

Galinio taško testavimas

Kai gavėjas ir Signing secret paruošti, aktyviame galiniame taške spustelėkite „Test“.

Maildroppa iš karto siunčia vieną pasirašytą užklausą naudodama išsaugotą galinio taško URL ir pasirinktines antraštes. Atidarytame redaktoriuje neišsaugoti pakeitimai į testą neįtraukiami.

Testo naudingojoje apkrovoje naudojamas įvykio tipas webhook.test, o livemode nustatytas į 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."
  }
}

Sugeneruoti ID ir laiko žyma kiekvienam tikram testui skiriasi.

Atliekamas lygiai vienas HTTP bandymas. Testiniai pristatymai neįtraukiami į gamybinį pakartojimų grafiką ir negali būti pakartoti.

Užklausai pasibaigus, rezultatų skydelyje rodoma:

• Test success arba Test failed
• Event ID
• HTTP būsena, kai buvo gautas atsakymas
• Trukmė
• Delivery ID
• Informacija apie klaidą, kai prieinama
• Atsakymo ištrauka, kai gavėjas grąžino turinį

Testas taip pat rodomas Delivery history su Test ženkleliu. Naudokite „Test“ filtrą, kad būtų rodomos tik testinės užklausos.

Gamybinės naudingosios apkrovos supratimas

Gamybiniai paskyros įvykiai naudoja bendrą JSON voką:

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

Aukščiausio lygio savybės reiškia:

• id — Event ID. Jis sutampa su X-Maildroppa-Event-Id.
• type — Įvykių redaktoriuje pasirinktas įvykio raktas.
• schema_version — Naudingosios apkrovos schemos versija. Naudokite ją spręsdami, kaip analizuoti įvykį.
• created_at — Laikas, kada sukurta įvykio naudingoji apkrova, UTC laiko juostoje.
• livemode — true gamybiniams įvykiams ir false testiniams įvykiams.
• data — Konkretaus įvykio turinys.

Nukreipkite įvykius pagal tikslią type reikšmę. Nepaisykite papildomų savybių, kurių jūsų integracijai nereikia, kad suderinami naudingosios apkrovos papildymai nesugadintų gavėjo.

Prenumeratoriaus įvykio naudingoji apkrova

Prenumeratoriaus įvykiuose dabartinis prenumeratoriaus atvaizdas pateikiamas data.subscriber viduje:

{
  "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 ir tags yra masyvai. Jie gali būti tušti. Prenumeratoriaus savybė taip pat gali būti null, kai reikšmės nėra, todėl jūsų gavėjas turėtų vadovautis naudinga apkrovos schema, o ne manyti, kad kiekviena pasirinktinė profilio reikšmė pateikiama.

Žymos įvykio naudingoji apkrova

Žymų įvykiuose pateikiami prenumeratorius ir įvykį sukėlusi žyma:

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

Naudojant subscriber.tag_removed, data.tag vis dar identifikuoja pašalintą žymą, nors dabartiniame prenumeratoriaus tags masyve jos nebėra.

Event ID, Delivery ID ir idempotentiškumas

Event ID ir Delivery ID paskirtis skiriasi.

Event ID

Event ID identifikuoja verslo įvykį. Jis pateikiamas:

• Aukščiausio lygio naudingojoje apkrovos id savybėje.
• X-Maildroppa-Event-Id užklausos antraštėje.
• Delivery history.

Tas pats įvykis gali būti siunčiamas keliems užsiprenumeravusiems galiniams taškams. Šie pristatymai turi tą patį Event ID.

Pakartotiniai bandymai ir rankiniai pakartojimai taip pat išlaiko pradinį Event ID. Išsaugokite apdorotus Event ID ir užtikrinkite, kad verslo veiksmas būtų idempotentiškas, kad pakartotinė užklausa nesukurtų pasikartojančių kontaktų, nepakartotų negrįžtamo veiksmo ar nepritaikytų to paties pakeitimo du kartus.

Delivery ID

Delivery ID identifikuoja vieną pristatymo įrašą. Jis pateikiamas:

• X-Maildroppa-Delivery-Id užklausos antraštėje.
• Delivery history.

Kiekvienas galinio taško pristatymas turi savo Delivery ID. Rankinis pakartojimas sukuria naują Delivery ID, išlaikydamas pradinį Event ID.

Techniniam sekimui ir pagalbai naudokite Delivery ID. Verslo lygio dublikatų šalinimui naudokite Event ID.

Teisingo HTTP atsakymo grąžinimas

Maildroppa atsakymus klasifikuoja taip:

• Bet koks 2xx atsakymas pristatymą pažymi kaip sėkmingą.
• 408 Request Timeout, 429 Too Many Requests ir 5xx atsakymai yra laikinos klaidos, todėl juos galima pakartoti.
• Laikinos tinklo klaidos pakartojamos.
• Peradresavimai ir kiti 3xx atsakymai nesekami ir laikomi galutinėmis klaidomis.
• Kiti 4xx atsakymai laikomi galutinėmis klaidomis ir nepakartojami.

Grąžinkite 200, 202 arba 204 tik tada, kai įvykis saugiai priimtas. Jei apdorojimas užtrunka, pirmiausia išsaugokite įvykį ir grąžinkite sėkmingą atsakymą, o lėtesnį darbą atlikite asinchroniškai.

Negrąžinkite peradresavimo į kitą webhook URL. Vietoje to sukonfigūruokite galutinį URL Maildroppa.

Automatinio pakartojimo grafikas

Gamybiniai pristatymai gali atlikti iki septynių HTTP bandymų.

Po pakartojamos klaidos Maildroppa suplanuoja kitą bandymą su šiais intervalais:

1. Po 1 bandymo: 1 minutė
2. Po 2 bandymo: 5 minutės
3. Po 3 bandymo: 30 minučių
4. Po 4 bandymo: 2 valandos
5. Po 5 bandymo: 12 valandų
6. Po 6 bandymo: 24 valandos

Jei 7 bandymas vis dar gauna pakartojamą klaidą, pristatymas tampa Dead ir daugiau automatinių bandymų neplanuojama.

Grafikas skaičiuojamas nuo kiekvieno nesėkmingo bandymo. Faktinis pristatymo laikas gali būti šiek tiek vėlesnis, nes pristatymai apdorojami asinchroniškai ir jiems taip pat taikomi sistemos apsaugos apribojimai.

Jei įmanoma, ištaisykite laikiną gavėjo problemą prieš rodomą „Next retry“ laiką. Jei automatiniai bandymai baigėsi, gavėjui vėl veikiant naudokite Replay.

Delivery history supratimas

Delivery history priklauso šiuo metu pasirinktam galiniam taškui. Galinio taško URL rodomas skilties antraštėje, kad galėtumėte patvirtinti, kurios istorijos peržiūrą atliekate.

Naudokite šiuos filtrus:

• All — Rodo gamybinius ir testinius pristatymus.
• Production — Rodo tik tiesioginių įvykių pristatymus.
• Test — Rodo tik rankinius testus.

Spustelėkite „Refresh“, kad gautumėte naujausią būseną. Istorijos nereikia palikti atidarytos, kol Maildroppa siunčia arba kartoja pristatymą.

Puslapyje rodoma 50 naujausių pristatymų pagal pasirinktą filtrą.

Pristatymo stulpeliai

Kiekvienoje eilutėje pateikiama:

• Created — Kada sukurtas pristatymo įrašas.
• State — Pending, Success, Failed arba Dead.
• HTTP — Atsakymo būsena, bandymų skaičius ir trukmė, taip pat kito pakartojimo laikas, kai taikoma.
• Subscriber — Prenumeratoriaus el. paštas, kai įvykis susietas su prenumeratoriumi.
• Delivery — Įvykio tipas, Event ID ir Delivery ID.
• Actions — Replay, kai pristatymas tinkamas.

Jei HTTP užklausa nebuvo atlikta, HTTP stulpelyje rodoma „No HTTP attempt“. Taip gali nutikti, kai Maildroppa atmeta užklausą prieš ją išsiųsdama, pavyzdžiui, kai trūksta Signing secret arba išsaugotos paskirties vietos nebegalima saugiai naudoti.

Kai prieinama, eilutėje taip pat rodomos gavėjo grąžintos Error ir Response excerpt. Nesiųskite paslapčių ar jautrių asmens duomenų webhook atsakymo turinyje, nes dalis šio atsakymo gali būti rodoma paskyros pristatymo žurnale.

Pristatymo būsenos

Pending reiškia, kad pristatymas laukia pirmojo bandymo arba suplanuoto pakartojimo. „Next retry“ rodoma, kai suplanuotas kitas bandymas.

Success reiškia, kad gavėjas grąžino 2xx atsakymą. Daugiau automatinių bandymų nereikia.

Failed reiškia, kad pristatymas baigėsi dėl nepakartojamos problemos, buvo atmestas prieš HTTP bandymą arba sustabdytas prieš išsiunčiant.

Dead reiškia, kad visi automatiniai bandymai dėl pakartojamos problemos buvo panaudoti, bet sėkmingas atsakymas negautas.

Istorijos saugojimas

Pristatymo įrašai saugomi ribotą laiką:

• Sėkmingi gamybiniai pristatymai: 30 dienų
• Nesėkmingi gamybiniai pristatymai: 90 dienų
• Dead gamybiniai pristatymai: 90 dienų
• Testiniai pristatymai: 30 dienų

Kai reikia ilgesnės audito istorijos, saugokite savo integracijos žurnalus. Saugokite Event ID ir Delivery ID, tačiau be reikalo nesaugokite paslapčių.

Pristatymo pakartojimas

Spustelėkite „Replay“, kai užbaigtą gamybinį pristatymą reikia bandyti dar kartą.

Replay galimas gamybiniams pristatymams, kurių būsena Success, Failed arba Dead. Jis negalimas, kol pristatymas yra Pending, o testinių pristatymų pakartoti negalima.

Pakartojimas:

• Sukuria naują Pending pristatymą.
• Sukuria naują Delivery ID.
• Išlaiko pradinį Event ID.
• Išlaiko pradinį įvykio tipą ir JSON naudingąją apkrovą.
• Naudoja pradinį išsaugotą paskirties URL ir pasirinktinių antraščių momentinę kopiją.
• Ruošiant naują užklausą naudoja dabartinį Signing secret.

Replay neatkuria naudingosios apkrovos pagal dabartinius prenumeratoriaus duomenis. Jis iš naujo siunčia pradinę įvykio momentinę kopiją. Taip pakartojimas tampa audituojamas ir istorinis įvykis nepakeičia reikšmės nepastebimai.

Vienu metu gali būti Pending tik vienas to paties šaltinio pristatymo pakartojimas. Prieš prašydami kito pakartojimo palaukite, kol dabartinis baigsis.

Prieš pakartodami įsitikinkite, kad galinis taškas yra Active. Jei galinis taškas neaktyvus, eilėje esantis pakartojimas negalės būti sėkmingai pristatytas.

Kadangi gavėjas galėjo užbaigti verslo veiksmą net tada, kai Maildroppa negavo sėkmingo atsakymo, pakartojimas gali sukurti pasikartojančią užklausą. Event ID dublikatų šalinimas apsaugo prijungtą sistemą nuo pakartotinio veiksmo atlikimo.

Galinio taško redagavimas

Spustelėkite „Edit“, kad pakeistumėte URL, įvykių pasirinkimą, pasirinktines antraštes arba aktyvią būseną.

Prieš išsaugodami:

1. Patvirtinkite, kad naujas URL jau pasiekiamas.
2. Palikite išsaugotų antraščių reikšmių laukus tuščius, jei jos turi likti nepakeistos.
3. Įveskite naują reikšmę kiekvienai pervadintai antraštei.
4. Peržiūrėkite įvykių pasirinkimą, kad netyčia nepašalintumėte reikalingų pranešimų.
5. Išsaugokite ir išsiųskite naują Test webhook.

Atminkite, kad eilėje esantys pristatymai išlaiko esamą URL ir pasirinktinių antraščių momentinę kopiją. Išbandykite naują konfigūraciją būsimiems pristatymams, nemanydami, kad ji pakeis senesnę eilėje esančią užklausą.

Galinio taško išaktyvinimas

Naudokite On/Off jungiklį, kai norite pristabdyti integraciją neištrindami jos konfigūracijos ir istorijos.

Kai galinis taškas išjungiamas:

• Nauji įvykiai į jį nebeįtraukiami į eilę.
• Pending pristatymai, kurie dar nebuvo paimti siuntimui, pažymimi Failed.
• Test išjungiamas.
• Galinis taškas lieka pasiekiamas redagavimui ir vėlesniam aktyvinimui.

Užklausa, kuri išaktyvinimo momentu jau vykdoma, vis tiek gali būti užbaigta. Jei šis skirtumas svarbus jūsų integracijai, patikrinkite Delivery history po galinio taško išjungimo.

Įvykiai, praleisti galiniam taškui esant neaktyviam, nepapildomi atgaline data, kai vėl jį įjungiate.

Galinio taško ištrynimas

Kai galinis taškas nebeturėtų egzistuoti, spustelėkite „Delete“ ir patvirtinkite įspėjimą.

Ištrynus galinis taškas pašalinamas iš puslapio, būsimi įvykių pristatymai sustabdomi, o laukiantys pristatymai, kurie dar nebuvo paimti siuntimui, pažymimi Failed.

Delete nėra laikino pristabdymo būdas. Naudokite On/Off jungiklį, kai konfigūracijos ar matomos istorijos gali vėl prireikti.

Prieš ištrindami užsirašykite visus Event ID ar Delivery ID, kurių dar reikia integracijos auditui.

Trikčių šalinimas

Galinio taško nepavyksta išsaugoti

Patikrinkite, ar:

• URL prasideda https://.
• URL naudoja viešą pagrindinio kompiuterio vardą ir 443 prievadą.
• URL nėra kintamųjų, prisijungimo informacijos ar fragmento.
• Pasirinktas bent vienas įvykis.
• Kiekviena Custom header turi unikalų pavadinimą ir reikšmę.
• Rezervuoti Maildroppa ir HTTP antraščių pavadinimai nenaudojami kaip pasirinktiniai pavadinimai.

Test išjungtas

Test galimas tik aktyviam galiniam taškui. Įjunkite galinį tašką arba redaguokite jį ir pasirinkite „Active“, tada prieš testuodami išsaugokite.

Test rodo, kad HTTP bandymas neatliktas

Jei būsena yra Missing, sugeneruokite Signing secret. Taip pat patikrinkite, ar paskirties pagrindinio kompiuterio vardas yra viešas ir vis dar tinkamai išsprendžiamas.

Užklausa gali būti atmesta prieš siunčiant, kai jos paslaptis, URL, pasirinktinės antraštės ar paskirties saugumo patikra yra netinkami.

Gavėjas grąžina 401 arba 403

Patikrinkite išsaugotą Custom header pavadinimą ir kredencialą. Jei reikšmė pasikeitė, redaguokite galinį tašką ir įveskite ją dar kartą.

Taip pat patikrinkite, ar gavėjas nepainioja savo API kredencialo su Maildroppa parašu. Pasirinktinė autorizacijos antraštė ir X-Maildroppa-Signature atlieka skirtingas funkcijas ir gali būti tikrinamos nepriklausomai.

Gavėjas grąžina peradresavimą

Maildroppa neseka peradresavimų. Pakeiskite galinio taško URL galutiniu viešu HTTPS URL ir išbandykite dar kartą.

Parašas nesutampa

Patvirtinkite, kad gavėjas:

• Naudoja dabartinį Signing secret.
• Naudoja tikslią X-Maildroppa-Timestamp reikšmę.
• Pasirašo <timestamp>.<raw request body>.
• Naudoja HMAC-SHA256 ir mažųjų šešioliktainių simbolių išvestį.
• Lygina visą reikšmę, įskaitant v1=.
• Atlieka palyginimą prieš JSON analizės pakeičiant turinį.

Tas pats įvykis gaunamas daugiau nei vieną kartą

Taip gali nutikti po tinklo sutrikimo, pakartotinio bandymo ar rankinio pakartojimo. Webhook pristatymo sistemoms įprasta užtikrinti pristatymą bent vieną kartą, o ne tiksliai vieną kartą.

Naudokite Event ID kaip idempotentiškumo raktą. Kai vėl gaunamas jau apdorotas Event ID ir papildomo veiksmo nereikia, grąžinkite 2xx atsakymą.

Pristatymas yra Pending

HTTP stulpelyje peržiūrėkite „Next retry“. Pakartojama 408, 429, 5xx arba laikina tinklo klaida išlaiko Pending būseną iki kito suplanuoto bandymo.

Po pakartojimo laiko spustelėkite „Refresh“, kad įkeltumėte naujausią būseną.

Pristatymas yra Dead

Panaudoti visi automatiniai bandymai. Pirmiausia sutvarkykite gavėją, įsitikinkite, kad galinis taškas yra Active, išsiųskite Test webhook ir tada gamybiniame pristatyme naudokite Replay.

Rekomenduojamas gamybinis kontrolinis sąrašas

Prieš pasikliaudami galiniu tašku gamyboje, patvirtinkite visus šiuos punktus:

1. Gavėjas naudoja stabilų viešą HTTPS URL su galiojančiu sertifikatu.
2. Signing secret saugoma ne išeities kode.
3. Parašas tikrinamas pagal nepakeistą neapdorotą turinį.
4. Seni laiko žymų įrašai atmetami pagal dokumentuotą toleranciją.
5. Gavėjas išsaugo ir pašalina Event ID dublikatus.
6. Gavėjas registruoja Event ID ir Delivery ID sekimui.
7. Lėtas apdorojimas atliekamas po to, kai įvykis patikimai priimtas.
8. 2xx atsakymas grąžinamas tik priimtiems įvykiams.
9. Pasirinktiniai kredencialai saugomi antraštėse, o ne URL.
10. Pasirinkti tik reikalingi įvykių tipai.
11. Test webhook sėkmingai įvykdomas ir tinkamai rodomas Delivery history.
12. Stebėjimo sistema įspėja, kai gamybiniai pristatymai pradeda grąžinti klaidas.

Įdiegus šias apsaugos priemones, Webhooks puslapis suteikia abi patikimos integracijos puses: saugų įvykių pristatymą jūsų programai ir aiškią veiklos istoriją Maildroppa sistemoje.