Konfigurēt tīmekļa āķus

Published: 2026. gada 16. jūlijs · Last updated: 2026. gada 21. jūlijs · By Marcus Biel

Tīmekļa āķi ļauj Maildroppa informēt citu lietotni, kad jūsu kontā notiek kaut kas svarīgs.

Tā vietā, lai atkārtoti vaicātu Maildroppa, vai abonents ir izveidots, atjaunināts, atteicies no abonēšanas vai tam ir piešķirta atzīme, jūsu lietotne var saņemt HTTPS pieprasījumu neilgi pēc notikuma.

Webhooks lapa ir galvenā vieta šai konta līmeņa integrācijai. Varat izveidot vairākus galapunktus, izvēlēties notikumus, ko saņem katrs galapunkts, pievienot autentifikācijas galvenes, pārbaudīt savienojumu, pārskatīt piegādes mēģinājumus un nepieciešamības gadījumā atkārtoti nosūtīt produkcijas notikumu.

Kā darbojas konta tīmekļa āķi

Konta tīmekļa āķis darbojas šādi:

1. Maildroppa notiek notikums, piemēram, tiek izveidots abonents.
2. Maildroppa atrod visus aktīvos galapunktus, kas ir pieteikušies šim notikumam.
3. Maildroppa izveido vienu piegādi katram atbilstošajam galapunktam.
4. JSON lietderīgā slodze tiek parakstīta ar jūsu konta tīmekļa āķu Signing secret.
5. Maildroppa nosūta HTTPS POST pieprasījumu uz saglabāto galapunkta URL.
6. Jūsu galapunkts pārbauda parakstu, saglabā vai apstrādā notikumu un atgriež HTTP atbildi.
7. Maildroppa reģistrē rezultātu sadaļā Delivery history un automātiski atkārto pagaidu kļūmju mēģinājumus.

Ja vienam notikumam ir pieteikušies vairāki galapunkti, katrs galapunkts saņem savu piegādi. Uzņēmējdarbības notikumam visiem tiem ir vienāds Event ID, savukārt katrai piegādei ir savs Delivery ID.

Konta tīmekļa āķi atšķiras no darbības “Send a webhook” automatizācijā. Konta tīmekļa āķi klausās atlasītos konta notikumus visā Maildroppa. Automatizācijas tīmekļa āķis tiek nosūtīts tikai tad, kad abonents sasniedz konkrēto darbību. Abi izmanto konta webhook Signing secret, tāpēc slepenās vērtības nomaiņa ietekmē visus izejošo tīmekļa āķu uztvērējus, kas pārbauda Maildroppa parakstus.

Webhooks lapas atvēršana

Atveriet “Settings”, izvērsiet “Developers” un atlasiet “Webhooks”.

Lapā ir trīs galvenās sadaļas:

• Signing secret
• Endpoints
• Atlasītā galapunkta Delivery history

Ja jums ir vairāk nekā viens galapunkts, atlasiet galapunkta rindu, lai parādītu tā Delivery history. Ja neesat konkrēti atlasījis nevienu, Maildroppa parāda saraksta pirmā galapunkta vēsturi.

Pirms galapunkta izveides

Pirms Maildroppa konfigurēšanas sagatavojiet uztvērēju savā serverī. Uztvērējam jābūt:

• Pieejamam, izmantojot publisku HTTPS URL.
• Gatavam pieņemt POST pieprasījumus ar application/json pamattekstu.
• Jāsaglabā neapstrādātais pieprasījuma pamatteksts, līdz Maildroppa paraksts ir pārbaudīts.
• Jāatgriež 2xx statuss tikai pēc tam, kad notikums ir droši pieņemts.
• Atkārtotas piegādes jāapstrādā idempotenti, izmantojot Event ID.
• Jāatbild ātri, nevis pieprasījuma laikā jāveic lēnas darbības.

Uzticams modelis ir pārbaudīt pieprasījumu, saglabāt Event ID un lietderīgo slodzi noturīgā rindā vai datubāzē, atgriezt 200 vai 204 un pēc tam apstrādāt uzņēmējdarbības darbību.

Neatklājiet izstrādes datoru, lokālā tīkla adresi vai neaizsargātu skriptu kā produkcijas tīmekļa āķa uztvērēju. Maildroppa pieņem tikai publiskus HTTPS mērķus un vēlreiz pārbauda galamērķi, kad tiek nosūtīta piegāde.

1. darbība: Signing secret ģenerēšana

---

Katrs Maildroppa tīmekļa āķa pieprasījums tiek parakstīts. Jūsu uztvērējs izmanto Signing secret, lai pārbaudītu, ka pieprasījumu ir izveidojis Maildroppa un ka pamatteksts pārsūtīšanas laikā nav mainīts.

Lapas augšdaļā Signing secret panelis parāda vienu no šiem stāvokļiem:

• Missing — Signing secret vēl nepastāv.
• Ready — Signing secret ir konfigurēta.
• Loading — Maildroppa izgūst pašreizējo statusu.

Kad statuss ir Missing, noklikšķiniet uz “Generate secret”.

Maildroppa nekavējoties parāda jauno slepeno vērtību. Tā sākas ar whsec_. Noklikšķiniet uz “Copy” un saglabājiet to slepeno vērtību pārvaldniekā vai aizsargātā vides konfigurācijā, ko izmanto jūsu uztvērējs.

Pilnā vērtība tiek parādīta tikai uzreiz pēc ģenerēšanas vai nomaiņas. Kad atkārtoti ielādējat lapu vai to atstājat, Maildroppa parāda tikai to, ka slepenā vērtība pastāv, un kad tā pēdējo reizi atjaunināta. Saglabāto slepeno vērtību tas vairs neatklāj.

Ja pazaudējat slepeno vērtību

Ja uztvērējam vairs nav pašreizējās slepenās vērtības, noklikšķiniet uz “Rotate secret” un saglabājiet no jauna parādīto vērtību.

Nomaiņa nekavējoties aizstāj iepriekšējo slepeno vērtību. Maildroppa nepatur abas vērtības pārejas periodā. Atjauniniet katru uztvērēju, kas izmanto šo konta slepeno vērtību, pirms sūtāt jaunus testus vai paļaujaties uz produkcijas piegādēm.

Jaunās piegādes, ieplānotie atkārtojumi, testi un atkārtoti nosūtījumi tiek parakstīti ar pašreizējo slepeno vērtību HTTP pieprasījuma veikšanas brīdī. Tas nozīmē, ka piegāde, kas izveidota pirms nomaiņas, vēlākā mēģinājumā joprojām var tikt parakstīta ar jauno slepeno vērtību.

Uztveriet slepeno vērtību kā paroli

Neievietojiet Signing secret pārlūka kodā, publiskā repozitorijā, URL, kļūdas lapā vai parastā lietotnes žurnālā.

Slepenā vērtība ir nepieciešama tikai servera puses uztvērējam. Ja uzskatāt, ka tā ir atklāta, nekavējoties nomainiet to un atjauniniet visus uztvērējus.

Tīmekļa āķa paraksta pārbaude

Katrā pieprasījumā ir šīs Maildroppa galvenes:

• X-Maildroppa-Event-Id — Identificē uzņēmējdarbības notikumu.
• X-Maildroppa-Delivery-Id — Identificē konkrēto piegādi.
• X-Maildroppa-Timestamp — Parakstīšanas laiks Unix sekundēs.
• X-Maildroppa-Signature — HMAC paraksts ar versiju.

Maildroppa nosūta arī:

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

Parakstam ir šāds formāts:

v1=<lowercase hexadecimal HMAC>

Maildroppa to izveido, izmantojot HMAC-SHA256. Parakstītais saturs ir laikspiedols, kam seko punkts un precīzais neapstrādātais JSON pieprasījuma pamatteksts:

<timestamp>.<raw request body>

Izmantojiet Signing secret kā HMAC atslēgu.

Šis Node.js piemērs parāda būtisko pārbaudes darbību. rawBody jābūt sākotnējiem pieprasījuma baitiem, nevis JSON, kas jau ir parsēts un vēlreiz serializēts.

import crypto from 'node:crypto';

export function verifyMaildroppaWebhook({ rawBody, timestamp, signature, signingSecret }) {
  const signedPayload = Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), rawBody]);

  const expectedSignature = `v1=${crypto
    .createHmac('sha256', signingSecret)
    .update(signedPayload)
    .digest('hex')}`;

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(expectedSignature, 'utf8');

  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

Pēc paraksta pārbaudes salīdziniet arī laikspiedolu ar sava servera laiku. Noraidiet pieprasījumus ārpus īsas pielaides, kas izvēlēta jūsu infrastruktūrai, piemēram, piecām minūtēm. Tas samazina risku, ka pārtverts derīgs pieprasījums tiks atkārtots daudz vēlāk.

Parsējiet un apstrādājiet JSON tikai pēc abu pārbaužu sekmīgas pabeigšanas.

Biežākie paraksta kļūdu cēloņi

Paraksts parasti neizdodas kāda no šiem iemesliem dēļ:

• Pēc nomaiņas uztvērējs izmanto vecu slepeno vērtību.
• Starpprogrammatūra parsēja vai mainīja JSON pirms paraksta aprēķināšanas.
• Uztvērējs paraksta tikai pamattekstu un izlaiž <timestamp>..
• Laikspiedols tiek uztverts kā formatēts datums, nevis precīza galvenes vērtība.
• Salīdzinājumā ir izlaists prefikss v1=.
• Aprēķinātais HMAC ir kodēts citādi, nevis kā mazie heksadecimālie burti.

Ja pārbaude neizdodas, reģistrējiet Event ID un Delivery ID, bet nekad nereģistrējiet Signing secret vai sensitīvas pielāgoto galveņu vērtības.

2. darbība: galapunkta pievienošana

---

Sadaļā Endpoints noklikšķiniet uz “Add endpoint”.

Redaktors sastāv no četrām daļām:

• Endpoint URL
• Events
• Custom headers
• Active status

Jauni galapunkti sākas kā Active, un visi redaktorā parādītie notikumi sākotnēji ir atlasīti. Pirms saglabāšanas pārskatiet atlasi, lai uztvērējs saņemtu tikai tam nepieciešamos paziņojumus.

Galapunkta URL konfigurēšana

Ievadiet pilnu publisko URL, kuram jāsaņem Maildroppa pieprasījumi, piemēram:

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

URL jāatbilst šīm prasībām:

• Tam jāizmanto https://.
• Tajā jābūt derīgam publiskam resursdatora nosaukumam.
• Tā garums nedrīkst pārsniegt 2 048 rakstzīmes.
• Tajā nedrīkst būt veidņu mainīgie ar { vai }.
• Tajā pirms resursdatora nosaukuma nedrīkst būt lietotājvārds vai parole.
• Tajā nedrīkst būt URL fragments, kas sākas ar #.
• Tam jāizmanto standarta HTTPS ports 443.
• Tajā nedrīkst izmantot localhost, neapstrādātu IP adresi vai resursdatora nosaukumu, kas atrisinās uz bloķētu privātu vai rezervētu tīklu.

Vaicājuma parametri tiek atbalstīti, taču neievietojiet URL API atslēgas vai citas slepenas vērtības. URL ir redzami galapunktu sarakstā un piegāžu datos. Tā vietā izmantojiet Custom header akreditācijas datus.

Maildroppa neseko novirzēm. Saglabājiet galīgo HTTPS galamērķi, nevis URL, kas atgriež 301, 302, 307 vai 308.

Pirms nosūtīšanas galamērķa resursdatora nosaukums tiek atrisināts atkārtoti. Resursdatora nosaukums, kas vēlāk atrisinās uz privātu vai bloķētu adresi, tiek noraidīts pat tad, ja galapunkta saglabāšanas brīdī tas bija derīgs.

Notikumu izvēle

Atlasiet vismaz vienu notikumu. Galapunkts saņem tikai tos notikumu veidus, kas atlasīti tā redaktorā.

Lapā ir pieejamas šādas notikumu izvēles:

Subscriber Created — subscriber.created

Nosūtīts, kad Maildroppa kontā tiek izveidots abonents.

Izmantojiet šo notikumu, lai izveidotu atbilstošo kontaktpersonu CRM sistēmā, klientu datu platformā, iekšējā datubāzē vai citā sistēmā, kas apzinās atļaujas.

Neuztveriet šo notikumu kā pierādījumu tam, ka katra reģistrēšanās ir pabeigusi Double Opt-in. Abonenta statuss lietderīgajā slodzē apraksta pašreizējo stāvokli.

Subscriber Updated — subscriber.updated

Nosūtīts, kad mainās iebūvētā abonenta informācija vai pielāgoto lauku vērtības.

Izmantojiet pilno abonenta objektu lietderīgajā slodzē kā pašreizējo Maildroppa attēlojumu. Neuzskatiet, ka ir mainījies tikai kāds konkrēts rekvizīts.

Atzīmju piešķiršanai un noņemšanai ir atsevišķi notikumu veidi, lai tos varētu apstrādāt atsevišķi.

Subscriber Unsubscribed — subscriber.unsubscribed

Nosūtīts, kad abonents pēc atteikšanās darbības pāriet uz atteikšanās stāvokli.

Izmantojiet šo notikumu, lai savienotajās sistēmās kontaktpersonu iekļautu bloķēto kontaktpersonu sarakstā. Neabonējiet personu automātiski atkārtoti tikai tāpēc, ka cita sistēma joprojām norāda kontaktpersonu kā aktīvu.

Tag Added — subscriber.tag_added

Nosūtīts, kad abonentam tiek piešķirta atzīme.

Lietderīgā slodze satur abonentu un atzīmi, kas iesaistīti konkrētajās izmaiņās.

Tag Removed — subscriber.tag_removed

Nosūtīts, kad atzīme tiek noņemta no abonenta.

Lietderīgā slodze satur atjaunināto abonentu un noņemto atzīmi. Noņemtā atzīme tiek norādīta atsevišķi, lai gan abonenta pašreizējā tags masīvā tās vairs nav.

Form Submitted — form.submitted

Nosūtīts, kad apmeklētājs iesniedz Maildroppa reģistrēšanās veidlapu.

Uztveriet to kā veidlapas iesniegšanas signālu, nevis apstiprinājumu, ka Double Opt-in ir pabeigts. Jebkurai darbplūsmai, kurai nepieciešams apstiprināts abonements, jāturpina ievērot abonenta pašreizējais statuss un apstiprināšanas process.

Izmantojiet atsevišķus galapunktus, ja atbildības atšķiras

Varat nosūtīt dažādus notikumus dažādām sistēmām. Piemēram:

• Nosūtīt abonentu un atzīmju notikumus CRM sistēmai.
• Nosūtīt atteikšanās notikumus bloķēšanas pakalpojumam.
• Nosūtīt veidlapas iesniegšanas notikumus analītikas konveijeram.

Atsevišķi galapunkti samazina nevajadzīgu datplūsmu un atvieglo kļūmju diagnosticēšanu. Katram galapunktam ir sava notikumu atlase, URL, pielāgotās galvenes, aktīvais statuss, testi un Delivery history.

Pielāgoto galveņu pievienošana

Pielāgotās galvenes nav obligātas. Izmantojiet tās, ja uztvērējam nepieciešama API atslēga, nesēja marķieris, nomnieka identifikators vai cita fiksēta galvene.

Noklikšķiniet uz “Add header”, pēc tam ievadiet Header name un Header value. Piemēroti piemēri:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Varat pievienot līdz 20 pielāgotajām galvenēm.

Galveņu nosaukumi:

• Ir obligāti.
• Var būt līdz 128 rakstzīmēm gari.
• Tajos jāizmanto derīgas HTTP galvenes nosaukuma rakstzīmes.
• Tiem jābūt unikāliem neatkarīgi no lielo un mazo burtu lietojuma.

Galveņu vērtības:

• Ir obligātas.
• Var būt līdz 2 000 rakstzīmēm garas.
• Tās nedrīkst saturēt rindu pārtraukumus.

Šie nosaukumi ir rezervēti, un tos nevar aizstāt ar pielāgotu galveni:

• Content-Type
• Content-Length
• Host
• User-Agent
• Jebkurš nosaukums, kas sākas ar X-Maildroppa-

Tas neļauj pielāgotai vērtībai aizstāt Maildroppa piegādes un paraksta galvenes.

Kā tiek glabāti galveņu noslēpumi

Maildroppa šifrē pielāgoto galveņu vērtības pirms to saglabāšanas. Saglabātās vērtības pārlūkprogrammai netiek atgrieztas lasāmā formā.

Kad vēlāk rediģējat galapunktu, vērtības laukā tiek rādīts “Stored value kept”. Atstājiet to tukšu, ja esošajai slepenajai vērtībai jāpaliek nemainītai. Ievadiet jaunu vērtību, lai to aizstātu.

Ja maināt galvenes nosaukumu, ievadiet vērtību vēlreiz. Maildroppa saglabā slepeno vērtību tikai tik ilgi, kamēr tās sākotnējais galvenes nosaukums paliek nemainīgs.

Noņemot galvenes rindu, pēc galapunkta saglabāšanas šī galvene tiek noņemta no turpmākajām piegādēm.

Pielāgoto galveņu vērtības saglabātajā pieprasījuma informācijā tiek uzskatītas par sensitīvām. Delivery history tās tiek maskētas, nevis parādītas.

Galapunkta aktivizēšana vai deaktivizēšana

Atstājiet “Active” atlasītu, ja galapunkts ir gatavs nekavējoties saņemt notikumus.

Noņemiet atlasi, ja vēlaties saglabāt konfigurāciju, nesākot piegādes. Galapunktu vēlāk varat aktivizēt galapunktu sarakstā.

Neaktīvs galapunkts:

• Nesaņem jaunus notikumus.
• Nevar nosūtīt Test webhook.
• Paliek redzams un rediģējams.
• Saglabā pieejamu esošo Delivery history.

Galapunkta aktivizēšana neatjauno notikumus, kas notika tā neaktivitātes laikā.

Kad URL, notikumu atlase, galvenes un statuss ir pareizi, noklikšķiniet uz “Save”.

Galapunktu saraksta izpratne

Katrā galapunkta rindā ir redzams:

• Galamērķa URL.
• Active vai Inactive emblēma.
• Abonētie notikumu veidi.
• Pielāgoto galveņu skaits.
• Laiks, kad galapunkts pēdējo reizi atjaunināts.

Pieejamās darbības ir:

• On/Off — Aktivizē vai deaktivizē galapunktu.
• Test — Nosūta vienu tūlītēju testa pieprasījumu aktīvam galapunktam.
• Edit — Maina URL, notikumus, galvenes vai aktīvo statusu.
• Delete — Pēc apstiprināšanas neatgriezeniski noņem galapunkta konfigurāciju.

Atlasiet rindas galveno daļu, lai zem saraksta atvērtu attiecīgā galapunkta Delivery history.

Kā saglabātās izmaiņas ietekmē esošās piegādes

Konta notikums izveido piegādi ar galapunkta URL, lietderīgās slodzes un pielāgoto galveņu momentuzņēmumu tajā brīdī.

URL vai pielāgoto galveņu rediģēšana ietekmē jaunizveidotās piegādes. Piegāde, kas jau atrodas rindā, saglabā sākotnējo galamērķi un saglabāto galveņu konfigurāciju.

Arī atlasīto notikumu maiņa ietekmē tikai vēlāk notiekošos notikumus. Maildroppa retrospektīvi neizveido piegādes notikumu veidiem, kas notikuma brīdī nebija atlasīti.

Signing secret atšķiras: tā tiek nolasīta, kad tiek sagatavots HTTP pieprasījums. Tāpēc gaidošā piegāde vai atkārtots nosūtījums var izmantot tikko nomainītu Signing secret, pat ja tās lietderīgā slodze un galapunkta momentuzņēmums tika izveidoti agrāk.

Galapunkta testēšana

Pēc tam, kad uztvērējs un Signing secret ir gatavi, aktīvam galapunktam noklikšķiniet uz “Test”.

Maildroppa nekavējoties nosūta vienu parakstītu pieprasījumu, izmantojot saglabāto galapunkta URL un saglabātās pielāgotās galvenes. Atvērtā redaktora nesaglabātās izmaiņas testā netiek iekļautas.

Testa lietderīgā slodze izmanto notikuma tipu webhook.test un iestata livemode uz 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."
  }
}

Ģenerētie ID un laikspiedols katram reālajam testam atšķiras.

Tests veic tieši vienu HTTP mēģinājumu. Testa piegādes netiek iekļautas produkcijas atkārtojumu grafikā, un tās nevar atkārtoti nosūtīt.

Pēc pieprasījuma pabeigšanas rezultātu panelī tiek rādīts:

• Test success vai Test failed
• Event ID
• HTTP statuss, ja atbilde tika saņemta
• Ilgums
• Delivery ID
• Kļūdas informācija, ja pieejama
• Atbildes fragments, ja uztvērējs atgrieza pamattekstu

Tests tiek parādīts arī Delivery history ar Test emblēmu. Izmantojiet filtru “Test”, lai parādītu tikai testa pieprasījumus.

Produkcijas lietderīgās slodzes izpratne

Produkcijas konta notikumi izmanto kopīgu JSON aploksni:

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

Augstākā līmeņa rekvizīti nozīmē:

• id — Event ID. Tas atbilst X-Maildroppa-Event-Id.
• type — Notikuma atslēga, kas atlasīta galapunkta redaktorā.
• schema_version — Lietderīgās slodzes shēmas versija. Izmantojiet to, lemjot, kā parsēt notikumu.
• created_at — Lietderīgās slodzes izveides laiks UTC.
• livemode — true produkcijas notikumiem un false testa notikumiem.
• data — Notikumam specifiskais saturs.

Maršrutējiet notikumus pēc precīzas type vērtības. Ignorējiet papildu rekvizītus, kas jūsu integrācijai nav nepieciešami, lai saderīgi lietderīgās slodzes papildinājumi neizraisītu uztvērēja darbības pārtraukumu.

Abonenta notikuma lietderīgā slodze

Abonenta notikumi satur pašreizējo abonenta attēlojumu data.subscriber iekšpusē:

{
  "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 un tags ir masīvi. Tie var būt tukši. Abonenta rekvizīts var būt arī null, ja vērtības nav, tāpēc uztvērējam jāseko lietderīgās slodzes shēmai, nevis jāpieņem, ka katra izvēles profila vērtība ir norādīta.

Atzīmes notikuma lietderīgā slodze

Atzīmes notikumi satur gan abonentu, gan atzīmi, kas izraisīja notikumu:

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

Attiecībā uz subscriber.tag_removed data.tag joprojām identificē noņemto atzīmi, lai gan abonenta pašreizējā tags masīvā tās vairs nav.

Event ID, Delivery ID un idempotence

Event ID un Delivery ID kalpo dažādiem mērķiem.

Event ID

Event ID identificē uzņēmējdarbības notikumu. Tas parādās:

• Lietderīgās slodzes augstākā līmeņa rekvizītā id.
• Pieprasījuma galvenē X-Maildroppa-Event-Id.
• Delivery history.

Vienu un to pašu notikumu var nosūtīt vairākiem abonētiem galapunktiem. Šīm piegādēm ir kopīgs Event ID.

Atkārtojumi un manuāli atkārtoti nosūtījumi arī saglabā sākotnējo Event ID. Saglabājiet apstrādātos Event ID un padariet uzņēmējdarbības darbību idempotentu, lai atkārtots pieprasījums neradītu dublētus kontaktus, neatkārtotu neatgriezenisku darbību vai nepiemērotu vienas un tās pašas izmaiņas divreiz.

Delivery ID

Delivery ID identificē vienu piegādes ierakstu. Tas parādās:

• Pieprasījuma galvenē X-Maildroppa-Delivery-Id.
• Delivery history.

Katrai galapunkta piegādei ir savs Delivery ID. Manuāla atkārtota nosūtīšana izveido jaunu Delivery ID, saglabājot sākotnējo Event ID.

Izmantojiet Delivery ID tehniskai izsekošanai un atbalstam. Izmantojiet Event ID uzņēmējdarbības līmeņa dublēšanas novēršanai.

Pareizas HTTP atbildes atgriešana

Maildroppa klasificē atbildes šādi:

• Jebkura 2xx atbilde atzīmē piegādi kā sekmīgu.
• 408 Request Timeout, 429 Too Many Requests un 5xx atbildes ir pagaidu kļūmes, un tās var atkārtot.
• Tīkla kļūmes, kas var būt pagaidu, tiek atkārtotas.
• Novirzēm un citām 3xx atbildēm neseko, un tās tiek uzskatītas par galīgām kļūmēm.
• Citas 4xx atbildes tiek uzskatītas par galīgām kļūmēm un netiek atkārtotas.

Atgrieziet 200, 202 vai 204 tikai tad, kad notikums ir droši pieņemts. Ja apstrāde aizņem laiku, vispirms saglabājiet notikumu un atgrieziet sekmīgu atbildi, bet lēnāko darbu veiciet asinhroni.

Neatgrieziet novirzi uz citu tīmekļa āķa URL. Tā vietā konfigurējiet galīgo URL Maildroppa.

Automātisko atkārtojumu grafiks

Produkcijas piegādes var veikt līdz septiņiem HTTP mēģinājumiem.

Pēc atkārtojamas kļūmes Maildroppa ieplāno nākamo mēģinājumu ar šādiem intervāliem:

1. Pēc 1. mēģinājuma: 1 minūte
2. Pēc 2. mēģinājuma: 5 minūtes
3. Pēc 3. mēģinājuma: 30 minūtes
4. Pēc 4. mēģinājuma: 2 stundas
5. Pēc 5. mēģinājuma: 12 stundas
6. Pēc 6. mēģinājuma: 24 stundas

Ja 7. mēģinājums joprojām saņem atkārtojamu kļūmi, piegāde kļūst Dead, un turpmāki automātiski mēģinājumi vairs netiek ieplānoti.

Grafiks tiek mērīts no katra atsevišķā neveiksmīgā mēģinājuma. Faktiskais piegādes laiks var būt nedaudz vēlāks, jo piegādes tiek apstrādātas asinhroni un uz tām attiecas arī sistēmas aizsardzības ierobežojumi.

Kad vien iespējams, novērsiet pagaidu uztvērēja problēmu pirms parādītā “Next retry” laika. Ja automātiskie mēģinājumi ir beigušies, izmantojiet Replay pēc tam, kad uztvērējs atkal darbojas.

Delivery history izpratne

Delivery history pieder pašlaik atlasītajam galapunktam. Galapunkta URL tiek parādīts sadaļas virsrakstā, lai varētu apstiprināt, kuru vēsturi skatāt.

Izmantojiet šos filtrus:

• All — Parāda produkcijas un testa piegādes.
• Production — Parāda tikai reālo notikumu piegādes.
• Test — Parāda tikai manuālos testus.

Noklikšķiniet uz “Refresh”, lai izgūtu jaunāko stāvokli. Vēsturei nav jābūt atvērtai, kamēr Maildroppa sūta vai atkārto piegādi.

Lapā tiek parādītas jaunākās 50 atlasītajam filtram atbilstošās piegādes.

Piegādes kolonnas

Katrā rindā ir:

• Created — Kad tika izveidots piegādes ieraksts.
• State — Pending, Success, Failed vai Dead.
• HTTP — Atbildes statuss, mēģinājumu skaits, ilgums un nākamā atkārtojuma laiks, ja piemērojams.
• Subscriber — Abonenta e-pasts, ja notikums ir saistīts ar abonentu.
• Delivery — Notikuma tips, Event ID un Delivery ID.
• Actions — Replay, ja piegāde tam atbilst.

Ja HTTP pieprasījums netika veikts, HTTP kolonnā tiek rādīts “No HTTP attempt”. Tas var notikt, ja Maildroppa noraida pieprasījumu pirms nosūtīšanas, piemēram, ja trūkst Signing secret vai saglabāto galamērķi vairs nevar droši izmantot.

Ja pieejams, rindā tiek rādīta arī Error un uztvērēja atgrieztais Response excerpt. Tīmekļa āķa atbildes pamattekstā neatgrieziet slepenas vērtības vai sensitīvus personas datus, jo daļa šīs atbildes var parādīties konta piegāžu žurnālā.

Piegādes stāvokļi

Pending nozīmē, ka piegāde gaida pirmo mēģinājumu vai ieplānoto atkārtojumu. “Next retry” tiek parādīts, kad ir ieplānots vēl viens mēģinājums.

Success nozīmē, ka uztvērējs atgrieza 2xx atbildi. Turpmāki automātiski mēģinājumi nav nepieciešami.

Failed nozīmē, ka piegāde beidzās ar neatkārtojamu problēmu, tika noraidīta pirms HTTP mēģinājuma vai apturēta pirms nosūtīšanas.

Dead nozīmē, ka visi automātiskie mēģinājumi atkārtojamas problēmas gadījumā tika izmantoti, nesaņemot sekmīgu atbildi.

Vēstures glabāšanas ilgums

Piegāžu ieraksti tiek glabāti ierobežotu laiku:

• Sekmīgas produkcijas piegādes: 30 dienas
• Neveiksmīgas produkcijas piegādes: 90 dienas
• Dead produkcijas piegādes: 90 dienas
• Testa piegādes: 30 dienas

Ja nepieciešama ilgāka audita vēsture, glabājiet savus integrācijas žurnālus. Saglabājiet Event ID un Delivery ID, bet nevajadzīgi neglabājiet slepenās vērtības.

Piegādes atkārtota nosūtīšana

Noklikšķiniet uz “Replay”, ja pabeigta produkcijas piegāde ir jāizmēģina vēlreiz.

Replay ir pieejams produkcijas piegādēm ar stāvokli Success, Failed vai Dead. Tas nav pieejams, kamēr piegāde ir Pending, un testa piegādes nevar atkārtoti nosūtīt.

Atkārtota nosūtīšana:

• Izveido jaunu Pending piegādi.
• Izveido jaunu Delivery ID.
• Saglabā sākotnējo Event ID.
• Saglabā sākotnējo notikuma tipu un JSON lietderīgo slodzi.
• Izmanto sākotnējo saglabātā mērķa URL un pielāgoto galveņu momentuzņēmumu.
• Izmanto pašreizējo Signing secret, kad tiek sagatavots jaunais pieprasījums.

Atkārtota nosūtīšana neizveido lietderīgo slodzi no abonenta pašreizējiem datiem. Tā nosūta sākotnējo notikuma momentuzņēmumu. Tas padara atkārtotu nosūtīšanu pārbaudāmu un neļauj vēsturiskam notikumam nemanāmi mainīt nozīmi.

Vienlaikus Pending var būt tikai viena tā paša avota piegādes atkārtota nosūtīšana. Pirms pieprasāt citu, uzgaidiet, līdz šī atkārtotā nosūtīšana ir pabeigta.

Pirms atkārtotas nosūtīšanas pārliecinieties, ka galapunkts ir Active. Ja galapunkts ir neaktīvs, rindā ievietoto atkārtoto piegādi nevar sekmīgi nosūtīt.

Tā kā uztvērējs var būt pabeidzis uzņēmējdarbības darbību pat tad, ja Maildroppa nav saņēmis tā sekmīgo atbildi, atkārtota nosūtīšana var radīt dublētu pieprasījumu. Event ID dublēšanas novēršana aizsargā savienoto sistēmu no darbības atkārtošanas.

Galapunkta rediģēšana

Noklikšķiniet uz “Edit”, lai mainītu URL, notikumu atlasi, pielāgotās galvenes vai aktīvo statusu.

Pirms saglabāšanas:

1. Pārliecinieties, ka jaunais URL jau ir pieejams.
2. Atstājiet saglabāto galveņu vērtības tukšas, ja tām jāpaliek nemainīgām.
3. Ievadiet jaunu vērtību katrai pārdēvētajai galvenei.
4. Pārskatiet notikumu atlasi, lai nejauši netiktu noņemti nepieciešamie paziņojumi.
5. Saglabājiet un nosūtiet jaunu Test webhook.

Atcerieties, ka rindā ievietotās piegādes saglabā esošo URL un pielāgoto galveņu momentuzņēmumu. Pārbaudiet jauno konfigurāciju turpmākajām piegādēm, nevis pieņemiet, ka tā maina vecāku rindā ievietotu pieprasījumu.

Galapunkta deaktivizēšana

Izmantojiet On/Off slēdzi, ja vēlaties apturēt integrāciju, neizdzēšot tās konfigurāciju un vēsturi.

Kad galapunkts tiek izslēgts:

• Jaunie notikumi tam vairs netiek ievietoti rindā.
• Pending piegādes, kas vēl nav pārņemtas nosūtīšanai, tiek atzīmētas kā Failed.
• Test tiek atspējots.
• Galapunkts paliek pieejams rediģēšanai un vēlākai aktivizēšanai.

Pieprasījums, kas deaktivizēšanas brīdī jau tiek apstrādāts, joprojām var tikt pabeigts. Pēc galapunkta izslēgšanas pārbaudiet Delivery history, ja šī atšķirība ir svarīga jūsu integrācijai.

Notikumi, kas palaisti garām galapunkta neaktivitātes laikā, netiek papildināti, kad to atkal ieslēdzat.

Galapunkta dzēšana

Noklikšķiniet uz “Delete” un apstipriniet brīdinājumu, kad galapunktam vairs nevajadzētu pastāvēt.

Dzēšana noņem galapunktu no lapas, aptur turpmākās notikumu piegādes un neizdevušās atzīmē Pending piegādes, kas vēl nebija pārņemtas nosūtīšanai.

Delete nav paredzēts īslaicīgai apturēšanai. Izmantojiet On/Off slēdzi, ja konfigurācija vai tās redzamā vēsture jums vēlāk var būt nepieciešama.

Pirms dzēšanas pierakstiet visus Event ID vai Delivery ID, kas joprojām nepieciešami integrācijas auditam.

Problēmu novēršana

Galapunktu nevar saglabāt

Pārbaudiet, vai:

• URL sākas ar https://.
• URL izmanto publisku resursdatora nosaukumu un portu 443.
• URL nesatur mainīgos, pieteikšanās informāciju vai fragmentu.
• Ir atlasīts vismaz viens notikums.
• Katrai Custom header ir unikāls nosaukums un vērtība.
• Rezervētās Maildroppa un HTTP galvenes netiek izmantotas kā pielāgotie nosaukumi.

Test ir atspējots

Test ir pieejams tikai aktīvam galapunktam. Ieslēdziet galapunktu vai rediģējiet to un atlasiet “Active”, pēc tam pirms testēšanas saglabājiet.

Test neuzrāda HTTP mēģinājumu

Ģenerējiet Signing secret, ja statuss ir Missing. Pārbaudiet arī, vai galamērķa resursdatora nosaukums ir publisks un joprojām tiek pareizi atrisināts.

Pieprasījums var tikt noraidīts pirms nosūtīšanas, ja tā slepenā vērtība, URL, pielāgotās galvenes vai galamērķa drošības pārbaude nav derīga.

Uztvērējs atgriež 401 vai 403

Pārbaudiet saglabātās Custom header nosaukumu un akreditācijas datus. Ja tie ir mainīti, rediģējiet galapunktu un ievadiet vērtību vēlreiz.

Pārbaudiet arī, vai uztvērējs nejauc savu API akreditācijas informāciju ar Maildroppa parakstu. Pielāgota autorizācijas galvene un X-Maildroppa-Signature kalpo atšķirīgiem mērķiem un var tikt pārbaudītas neatkarīgi.

Uztvērējs atgriež novirzi

Maildroppa neseko novirzēm. Aizstājiet galapunkta URL ar galīgo publisko HTTPS URL un testējiet vēlreiz.

Paraksts nesakrīt

Pārliecinieties, ka uztvērējs:

• Izmanto pašreizējo Signing secret.
• Izmanto precīzu X-Maildroppa-Timestamp vērtību.
• Paraksta <timestamp>.<raw request body>.
• Izmanto HMAC-SHA256 un mazo heksadecimālo burtu izvadi.
• Salīdzina pilno vērtību, tostarp v1=.
• Veic salīdzināšanu pirms JSON parsēšanas, kas maina pamattekstu.

Tas pats notikums pienāk vairāk nekā vienu reizi

Tas var notikt pēc tīkla pārtraukuma, atkārtojuma vai manuālas atkārtotas nosūtīšanas. Tīmekļa āķu piegādes sistēmām ir normāli nodrošināt piegādi vismaz vienu reizi, nevis tieši vienu reizi.

Izmantojiet Event ID kā idempotences atslēgu. Atgrieziet 2xx atbildi, kad atkārtoti tiek saņemts jau apstrādāts Event ID un papildu darbība nav nepieciešama.

Piegāde ir Pending

HTTP kolonnā apskatiet “Next retry”. Atkārtojama 408, 429, 5xx vai pagaidu tīkla kļūme paliek Pending līdz nākamajam ieplānotajam mēģinājumam.

Pēc atkārtojuma laika noklikšķiniet uz “Refresh”, lai ielādētu jaunāko stāvokli.

Piegāde ir Dead

Visi automātiskie mēģinājumi tika izmantoti. Vispirms salabojiet uztvērēju, pārliecinieties, ka galapunkts ir Active, nosūtiet Test webhook un pēc tam produkcijas piegādei izmantojiet Replay.

Ieteicamais produkcijas kontrolsaraksts

Pirms paļaušanās uz galapunktu produkcijā apstipriniet visu tālāk norādīto:

1. Uztvērējs izmanto stabilu publisku HTTPS URL ar derīgu sertifikātu.
2. Signing secret tiek glabāta ārpus avota koda.
3. Paraksts tiek pārbaudīts, izmantojot nemainītu neapstrādāto pamattekstu.
4. Veci laikspiedoli tiek noraidīti saskaņā ar dokumentētu pielaidi.
5. Uztvērējs saglabā un deduplicē Event ID.
6. Uztvērējs reģistrē Event ID un Delivery ID izsekošanai.
7. Lēna apstrāde notiek pēc tam, kad notikums ir noturīgi pieņemts.
8. 2xx atbilde tiek atgriezta tikai pieņemtiem notikumiem.
9. Pielāgotie akreditācijas dati tiek glabāti galvenēs, nevis URL.
10. Tiek atlasīti tikai nepieciešamie notikumu veidi.
11. Test webhook ir sekmīgs un pareizi parādās Delivery history.
12. Uzraudzības sistēma brīdina, kad produkcijas piegādes sāk atgriezt kļūdas.

Izmantojot šos drošības pasākumus, Webhooks lapa nodrošina abas uzticamas integrācijas puses: drošu notikumu piegādi jūsu lietotnei un skaidru darbības vēsturi Maildroppa.