Konfiguro Webhooks

Published: 16 korrik 2026 · Last updated: 21 korrik 2026 · By Marcus Biel

Webhooks i lejojnë Maildroppa-s të njoftojë një aplikacion tjetër kur ndodh diçka e rëndësishme në llogarinë tuaj.

Në vend që ta pyesë vazhdimisht Maildroppa-n nëse një abonent u krijua, u përditësua, u çregjistrua ose iu caktua një etiketë, aplikacioni juaj mund të marrë një kërkesë HTTPS pak pas ndodhjes së ngjarjes.

Faqja Webhooks është vendi qendror për këtë integrim në të gjithë llogarinë. Mund të krijoni disa endpoint-e, të zgjidhni ngjarjet që merr secili endpoint, të shtoni koka autentikimi, të testoni lidhjen, të kontrolloni përpjekjet e dorëzimit dhe të ridërgoni një ngjarje prodhimi kur është e nevojshme.

Si funksionojnë Webhooks e llogarisë

Një webhook i llogarisë ndjek këtë proces:

1. Ndodh një ngjarje në Maildroppa, si krijimi i një abonenti.
2. Maildroppa gjen çdo endpoint aktiv që është abonuar në atë ngjarje.
3. Maildroppa krijon një dorëzim për çdo endpoint përkatës.
4. Payload-i JSON nënshkruhet me Signing secret të webhook-ut të llogarisë suaj.
5. Maildroppa dërgon një kërkesë HTTPS POST në URL-në e ruajtur të endpoint-it.
6. Endpoint-i juaj verifikon nënshkrimin, ruan ose përpunon ngjarjen dhe kthen një përgjigje HTTP.
7. Maildroppa regjistron rezultatin te Delivery history dhe i riprovon automatikisht dështimet e përkohshme.

Nëse disa endpoint-e abonohen në të njëjtën ngjarje, secili endpoint merr dorëzimin e vet. Ngjarja e biznesit ka të njëjtin Event ID për të gjithë, ndërsa çdo dorëzim ka Delivery ID-në e vet.

Webhook-et e llogarisë ndryshojnë nga një hap “Send a webhook” brenda një Automation. Webhook-et e llogarisë dëgjojnë për ngjarje të zgjedhura të llogarisë në të gjithë Maildroppa-n. Një webhook i Automation dërgohet vetëm kur një abonent arrin atë hap të caktuar. Të dyja përdorin Signing secret të webhook-ut të llogarisë, ndaj rotacioni i secret-it ndikon te çdo marrës webhook-u në dalje që verifikon nënshkrimet e Maildroppa-s.

Hapja e faqes Webhooks

Hapni “Settings”, zgjeroni “Developers” dhe zgjidhni “Webhooks”.

Faqja përmban tre zona kryesore:

• Signing secret
• Endpoints
• Delivery history për endpoint-in e zgjedhur

Kur keni më shumë se një endpoint, zgjidhni një rresht endpoint-i për të shfaqur Delivery history. Nëse nuk keni zgjedhur një të tillë shprehimisht, Maildroppa shfaq historikun e endpoint-it të parë në listë.

Para se të krijoni një endpoint

Përgatitni një marrës në serverin tuaj para se të konfiguroni Maildroppa-n. Marrësi duhet:

• Të jetë i disponueshëm përmes një URL-je publike HTTPS.
• Të pranojë kërkesa POST me trup application/json.
• Të ruajë trupin e papërpunuar të kërkesës derisa të verifikohet nënshkrimi i Maildroppa-s.
• Të kthejë status 2xx vetëm pasi ngjarja të jetë pranuar në mënyrë të sigurt.
• Të përpunojë në mënyrë idempotente dorëzimet e përsëritura duke përdorur Event ID.
• Të përgjigjet shpejt në vend që të kryejë punë të ngadaltë gjatë kërkesës.

Një model i besueshëm është të verifikoni kërkesën, të ruani Event ID dhe payload-in në një radhë ose bazë të dhënash të qëndrueshme, të ktheni 200 ose 204 dhe ta përpunoni veprimin e biznesit më pas.

Mos ekspozoni një kompjuter zhvillimi, adresë rrjeti lokal ose skript të pambrojtur si marrës webhook-u në prodhim. Maildroppa pranon vetëm objektiva publike HTTPS dhe e kontrollon destinacionin përsëri kur dërgohet një dorëzim.

Hapi 1: Gjeneroni Signing secret

Çdo kërkesë webhook-u e Maildroppa-s nënshkruhet. Marrësi juaj përdor Signing secret për të verifikuar se kërkesa u krijua nga Maildroppa dhe se trupi nuk u ndryshua gjatë transmetimit.

Në krye të faqes, paneli Signing secret shfaq një nga këto gjendje:

• Missing — Ende nuk ekziston asnjë Signing secret.
• Ready — Është konfiguruar një Signing secret.
• Loading — Maildroppa po merr statusin aktual.

Klikoni “Generate secret” kur statusi është Missing.

Maildroppa shfaq menjëherë secret-in e ri. Ai fillon me whsec_. Klikoni “Copy” dhe ruajeni në menaxherin e secret-eve ose në konfigurimin e mbrojtur të mjedisit që përdor marrësi juaj.

Vlera e plotë shfaqet vetëm menjëherë pas gjenerimit ose rotacionit. Kur ringarkoni faqen ose largoheni prej saj, Maildroppa tregon vetëm se ekziston një secret dhe kur u përditësua për herë të fundit. Secret-i i ruajtur nuk shfaqet përsëri.

Nëse humbni secret-in

Nëse marrësi nuk e ka më secret-in aktual, klikoni “Rotate secret” dhe ruani vlerën e re të shfaqur.

Rotacioni zëvendëson menjëherë secret-in e mëparshëm. Maildroppa nuk i ruan të dyja vlerat për një periudhë kalimi. Përditësoni çdo marrës që përdor këtë secret të llogarisë para se të dërgoni teste të tjera ose të mbështeteni te dorëzimet në prodhim.

Dorëzimet e reja, riprovimet e planifikuara, testet dhe ridërgimet nënshkruhen me secret-in aktual në momentin e kërkesës HTTP. Kjo do të thotë se një dorëzim i krijuar para rotacionit mund të nënshkruhet ende me secret-in e ri kur provohet më pas.

Trajtojeni secret-in si fjalëkalim

Mos e vendosni Signing secret në kodin e shfletuesit, në një repository publik, në një URL, në një faqe gabimi ose në një regjistër të zakonshëm aplikacioni.

Vetëm marrësi në server ka nevojë për secret-in. Nëse besoni se është ekspozuar, rrotullojeni dhe përditësoni menjëherë të gjithë marrësit.

Verifikimi i nënshkrimit të webhook-ut

Çdo kërkesë përmban këto koka të Maildroppa-s:

• X-Maildroppa-Event-Id — Identifikon ngjarjen e biznesit.
• X-Maildroppa-Delivery-Id — Identifikon këtë dorëzim të veçantë.
• X-Maildroppa-Timestamp — Koha e nënshkrimit si sekonda Unix.
• X-Maildroppa-Signature — Nënshkrimi HMAC me version.

Maildroppa dërgon gjithashtu:

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

Nënshkrimi ka këtë format:

v1=<lowercase hexadecimal HMAC>

Maildroppa e krijon me HMAC-SHA256. Përmbajtja e nënshkruar është timestamp-i, i ndjekur nga një pikë, i ndjekur nga trupi i saktë JSON i papërpunuar i kërkesës:

<timestamp>.<raw request body>

Përdorni Signing secret si çelësin HMAC.

Shembulli i mëposhtëm në Node.js tregon hapin thelbësor të verifikimit. rawBody duhet të jetë bajtet origjinale të kërkesës, jo JSON që është analizuar dhe serializuar përsëri.

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

Pas verifikimit të nënshkrimit, krahasoni gjithashtu timestamp-in me kohën e serverit tuaj. Refuzoni kërkesat jashtë një tolerance të shkurtër të zgjedhur për infrastrukturën tuaj, si pesë minuta. Kjo zvogëlon rrezikun që një kërkesë e vlefshme e kapur të ridërgohet shumë më vonë.

Analizoni dhe përpunoni JSON-in vetëm pasi të dyja kontrollet të kenë kaluar.

Shkaqe të zakonshme të gabimeve të nënshkrimit

Një nënshkrim zakonisht dështon për një nga këto arsye:

• Marrësi përdor një secret të vjetër pas rotacionit.
• Middleware-i analizoi ose ndryshoi JSON-in para llogaritjes së nënshkrimit.
• Marrësi nënshkruan vetëm trupin dhe lë jashtë <timestamp>..
• Timestamp-i trajtohet si datë e formatuar në vend të vlerës së saktë të kokës.
• Prefiksi v1= lihet jashtë krahasimit.
• HMAC-u i llogaritur kodohet ndryshe në vend të formatit heksadecimal me shkronja të vogla.

Regjistroni Event ID dhe Delivery ID kur verifikimi dështon, por mos regjistroni Signing secret ose vlerat e ndjeshme të kokave të personalizuara.

Hapi 2: Shtoni një endpoint

Klikoni “Add endpoint” në seksionin Endpoints.

Redaktori përmban katër pjesë:

• Endpoint URL
• Events
• Custom headers
• Active status

Endpoint-et e reja nisin si Active dhe të gjitha ngjarjet e shfaqura në redaktor zgjidhen fillimisht. Rishikoni përzgjedhjen para ruajtjes, në mënyrë që marrësi të marrë vetëm njoftimet që i nevojiten vërtet.

Konfigurimi i URL-së së endpoint-it

Vendosni URL-në e plotë publike që duhet të marrë kërkesat e Maildroppa-s, për shembull:

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

URL-ja duhet të plotësojë këto kërkesa:

• Duhet të përdorë https://.
• Duhet të përmbajë një hostname publik të vlefshëm.
• Mund të jetë deri në 2,048 karaktere e gjatë.
• Nuk mund të përmbajë variabla shablloni me { ose }.
• Nuk mund të përmbajë emër përdoruesi ose fjalëkalim para hostname-it.
• Nuk mund të përmbajë fragment URL-je që fillon me #.
• Duhet të përdorë portën standarde HTTPS 443.
• Nuk mund të përdorë localhost, adresë IP të papërpunuar ose hostname që zgjidhet në një rrjet privat ose të rezervuar të bllokuar.

Parametrat e query-t mbështeten, por mos vendosni çelësa API ose secret-e të tjera në URL. URL-të janë të dukshme në listën e endpoint-eve dhe në të dhënat e dorëzimeve. Përdorni një Custom header për kredencialet.

Maildroppa nuk ndjek ridrejtimet. Ruani destinacionin përfundimtar HTTPS dhe jo një URL që kthen 301, 302, 307 ose 308.

Hostname-i i destinacionit zgjidhet përsëri para dërgimit. Një hostname që më vonë zgjidhet në një adresë private ose të bllokuar refuzohet edhe nëse ishte i vlefshëm kur endpoint-i u ruajt.

Zgjedhja e ngjarjeve

Zgjidhni të paktën një ngjarje. Një endpoint merr vetëm llojet e ngjarjeve të zgjedhura në redaktorin e tij.

Faqja ofron këto zgjedhje ngjarjesh:

Subscriber Created — subscriber.created

Dërgohet kur krijohet një abonent në llogarinë Maildroppa.

Përdoreni këtë ngjarje për të krijuar kontaktin përkatës në një CRM, platformë të të dhënave të klientëve, bazë të dhënash të brendshme ose sistem tjetër që respekton lejet.

Mos e interpretoni këtë ngjarje si provë se çdo regjistrim ka përfunduar Double Opt-in. Statusi i abonentit në payload përshkruan gjendjen aktuale.

Subscriber Updated — subscriber.updated

Dërgohet kur ndryshojnë informacionet e integruara të abonentit ose vlerat e fushave të personalizuara.

Përdorni objektin e plotë të abonentit në payload si përfaqësimin aktual të Maildroppa-s. Shmangni supozimin se ka ndryshuar vetëm një pronë e caktuar.

Caktimet dhe heqjet e etiketave kanë llojet e tyre të ngjarjeve, në mënyrë që të trajtohen veçmas.

Subscriber Unsubscribed — subscriber.unsubscribed

Dërgohet kur abonenti kalon në gjendjen e çregjistruar përmes një veprimi çregjistrimi.

Përdoreni këtë ngjarje për ta përjashtuar kontaktin në sistemet e lidhura. Mos e abononi automatikisht përsëri personin vetëm sepse një sistem tjetër ende e shënon kontaktin si aktiv.

Tag Added — subscriber.tag_added

Dërgohet kur një etiketë i caktohet një abonenti.

Payload-i përmban abonentin dhe etiketën e përfshirë në këtë ndryshim të veçantë.

Tag Removed — subscriber.tag_removed

Dërgohet kur një etiketë hiqet nga një abonent.

Payload-i përmban abonentin e përditësuar dhe etiketën e hequr. Etiketa e hequr jepet veçmas edhe pse nuk është më e pranishme në vargun aktual tags të abonentit.

Form Submitted — form.submitted

Dërgohet kur një vizitor dërgon një formular regjistrimi të Maildroppa-s.

Trajtojeni këtë si sinjal dërgimi formulari, jo si konfirmim se Double Opt-in ka përfunduar. Çdo rrjedhë pune që kërkon një abonim të konfirmuar duhet të vazhdojë të respektojë statusin aktual të abonentit dhe procesin e konfirmimit.

Përdorni endpoint-e të veçanta kur përgjegjësitë ndryshojnë

Mund të dërgoni ngjarje të ndryshme në sisteme të ndryshme. Për shembull:

• Dërgoni ngjarjet e abonentëve dhe etiketave në një CRM.
• Dërgoni ngjarjet e çregjistrimit në një shërbim përjashtimi.
• Dërgoni ngjarjet e dërgimit të formularëve në një pipeline analitike.

Endpoint-et e veçanta reduktojnë trafikun e panevojshëm dhe e bëjnë më të lehtë diagnostikimin e dështimeve. Çdo endpoint ka përzgjedhjen e vet të ngjarjeve, URL-në, kokat e personalizuara, statusin aktiv, testet dhe Delivery history.

Shtimi i kokave të personalizuara

Kokat e personalizuara janë opsionale. Përdorini kur marrësi kërkon një çelës API, token bearer, identifikues tenant-i ose kokë tjetër fikse.

Klikoni “Add header”, më pas vendosni Header name dhe Header value. Shembuj të përshtatshëm përfshijnë:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Mund të shtoni deri në 20 koka të personalizuara.

Emrat e kokave:

• Janë të detyrueshëm.
• Mund të përmbajnë deri në 128 karaktere.
• Duhet të përdorin karaktere të vlefshme për emrat e kokave HTTP.
• Duhet të jenë unikë pavarësisht përdorimit të shkronjave të mëdha ose të vogla.

Vlerat e kokave:

• Janë të detyrueshme.
• Mund të përmbajnë deri në 2,000 karaktere.
• Nuk mund të përmbajnë rreshta të rinj.

Emrat e mëposhtëm janë të rezervuar dhe nuk mund të zëvendësohen nga një kokë e personalizuar:

• Content-Type
• Content-Length
• Host
• User-Agent
• Çdo emër që fillon me X-Maildroppa-

Kjo parandalon që një vlerë e personalizuar të zëvendësojë kokat e dorëzimit dhe nënshkrimit të Maildroppa-s.

Si ruhen secret-et e kokave

Maildroppa i enkripton vlerat e kokave të personalizuara para ruajtjes. Vlerat e ruajtura nuk i kthehen shfletuesit në formë të lexueshme.

Kur e redaktoni endpoint-in më vonë, fusha e vlerës shfaq “Stored value kept”. Lëreni bosh kur secret-i ekzistues duhet të mbetet i pandryshuar. Vendosni një vlerë të re për ta zëvendësuar.

Nëse ndryshoni emrin e kokës, vendoseni përsëri vlerën. Maildroppa e mban një secret të ruajtur vetëm për sa kohë emri origjinal i kokës mbetet i pandryshuar.

Heqja e një rreshti koke e heq atë kokë nga dorëzimet e ardhshme pasi endpoint-i të ruhet.

Vlerat e kokave të personalizuara trajtohen si të ndjeshme në informacionin e ruajtur të kërkesës. Ato maskohen në vend që të shfaqen në Delivery history.

Vendosja e endpoint-it si aktiv ose joaktiv

Lëreni “Active” të zgjedhur kur endpoint-i është gati të marrë ngjarje menjëherë.

Hiqeni zgjedhjen kur dëshironi ta ruani konfigurimin pa nisur dorëzimet. Mund ta aktivizoni endpoint-in më vonë nga lista e endpoint-eve.

Një endpoint joaktiv:

• Nuk merr ngjarje të reja.
• Nuk mund të dërgojë një Test webhook.
• Mbetet i dukshëm dhe i redaktueshëm.
• Mban të disponueshme Delivery history ekzistuese.

Aktivizimi i një endpoint-i nuk plotëson prapa ngjarjet që ndodhën kur ai ishte joaktiv.

Klikoni “Save” kur URL-ja, përzgjedhja e ngjarjeve, kokat dhe statusi të jenë të sakta.

Kuptimi i listës së endpoint-eve

Çdo rresht endpoint-i shfaq:

• URL-në e destinacionit.
• Një badge Active ose Inactive.
• Llojet e ngjarjeve të abonuara.
• Numrin e kokave të personalizuara.
• Kohën e përditësimit të fundit të endpoint-it.

Veprimet e disponueshme janë:

• On/Off — Aktivizon ose çaktivizon endpoint-in.
• Test — Dërgon një kërkesë testimi të menjëhershme në një endpoint aktiv.
• Edit — Ndryshon URL-në, ngjarjet, kokat ose statusin aktiv.
• Delete — Heq përgjithmonë konfigurimin e endpoint-it pas konfirmimit.

Zgjidhni pjesën kryesore të një rreshti për të hapur Delivery history të atij endpoint-i poshtë listës.

Si ndikojnë ndryshimet e ruajtura te dorëzimet ekzistuese

Një ngjarje llogarie krijon një dorëzim me një snapshot të URL-së së endpoint-it, payload-it dhe kokave të personalizuara në atë moment.

Redaktimi i URL-së ose kokave të personalizuara ndikon te dorëzimet e krijuara rishtazi. Një dorëzim që tashmë është në radhë ruan destinacionin dhe konfigurimin origjinal të kokave.

Ndryshimi i ngjarjeve të zgjedhura ndikon gjithashtu vetëm te ngjarjet që ndodhin më pas. Maildroppa nuk krijon dorëzime në mënyrë retroaktive për llojet e ngjarjeve që nuk ishin zgjedhur kur ndodhi ngjarja.

Signing secret është ndryshe: lexohet kur përgatitet kërkesa HTTP. Prandaj një dorëzim në pritje ose një ridërgim mund të përdorë një Signing secret të rrotulluar rishtazi edhe kur payload-i dhe snapshot-i i endpoint-it u krijuan më herët.

Testimi i një endpoint-i

Klikoni “Test” në një endpoint aktiv pasi marrësi dhe Signing secret të jenë gati.

Maildroppa dërgon menjëherë një kërkesë të nënshkruar duke përdorur URL-në e ruajtur të endpoint-it dhe kokat e personalizuara të ruajtura. Ndryshimet e paruajtura në një redaktor të hapur nuk përfshihen në test.

Payload-i i testit përdor llojin e ngjarjes webhook.test dhe vendos livemode në 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."
  }
}

ID-të dhe timestamp-i i gjeneruar ndryshojnë për çdo test real.

Një test bën saktësisht një përpjekje HTTP. Dorëzimet e testit nuk vendosen në planin e riprovimeve të prodhimit dhe nuk mund të ridërgohen.

Pas përfundimit të kërkesës, paneli i rezultatit shfaq:

• Test success ose Test failed
• Event ID
• Statusin HTTP, kur është marrë një përgjigje
• Kohëzgjatjen
• Delivery ID
• Informacionin e gabimit, kur është i disponueshëm
• Një fragment të përgjigjes, kur marrësi ka kthyer një trup

Testi shfaqet gjithashtu në Delivery history me një badge Test. Përdorni filtrin “Test” për të shfaqur vetëm kërkesat e testimit.

Kuptimi i payload-it të prodhimit

Ngjarjet e llogarisë në prodhim përdorin një envelope të përbashkët JSON:

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

Vetitë e nivelit të sipërm nënkuptojnë:

• id — Event ID. Përputhet me X-Maildroppa-Event-Id.
• type — Çelësi i ngjarjes i zgjedhur në redaktorin e endpoint-it.
• schema_version — Versioni i skemës së payload-it. Përdoreni kur vendosni si ta analizoni ngjarjen.
• created_at — Koha kur u krijua payload-i i ngjarjes, në UTC.
• livemode — true për ngjarjet e prodhimit dhe false për ngjarjet e testimit.
• data — Përmbajtja specifike e ngjarjes.

Drejtojini ngjarjet sipas vlerës së saktë të type. Injoroni vetitë shtesë që integrimi juaj nuk i nevojitet, në mënyrë që shtesat e pajtueshme të payload-it të mos e prishin marrësin.

Payload-i i ngjarjeve të abonentit

Ngjarjet e abonentit përmbajnë përfaqësimin aktual të abonentit brenda 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 dhe tags janë vargje. Mund të jenë bosh. Një veti e abonentit mund të jetë gjithashtu null kur nuk ekziston asnjë vlerë, ndaj marrësi juaj duhet të ndjekë skemën e payload-it në vend që të supozojë se çdo vlerë opsionale e profilit është e pranishme.

Payload-i i ngjarjeve të etiketave

Ngjarjet e etiketave përmbajnë si abonentin, ashtu edhe etiketën që shkaktoi ngjarjen:

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

Për subscriber.tag_removed, data.tag ende identifikon etiketën e hequr edhe pse vargu aktual tags i abonentit nuk e përmban më.

Event ID, Delivery ID dhe idempotenca

Event ID dhe Delivery ID shërbejnë për qëllime të ndryshme.

Event ID

Event ID identifikon ngjarjen e biznesit. Shfaqet në:

• Vetinë e nivelit të sipërm id të payload-it.
• Kokën e kërkesës X-Maildroppa-Event-Id.
• Delivery history.

E njëjta ngjarje mund t’u dërgohet disa endpoint-eve të abonuara. Këto dorëzime ndajnë të njëjtin Event ID.

Riprovimet dhe ridërgimet manuale ruajnë gjithashtu Event ID origjinal. Ruani Event ID-të e përpunuara dhe bëjeni veprimin e biznesit idempotent, në mënyrë që një kërkesë e përsëritur të mos krijojë kontakte dublikatë, të përsërisë një veprim të pakthyeshëm ose të zbatojë të njëjtin ndryshim dy herë.

Delivery ID

Delivery ID identifikon një rekord dorëzimi. Shfaqet në:

• Kokën e kërkesës X-Maildroppa-Delivery-Id.
• Delivery history.

Çdo dorëzim endpoint-i ka Delivery ID-në e vet. Një ridërgim manual krijon një Delivery ID të ri duke ruajtur Event ID origjinal.

Përdorni Delivery ID për gjurmim teknik dhe mbështetje. Përdorni Event ID për dedublikim në nivel biznesi.

Kthimi i përgjigjes së saktë HTTP

Maildroppa i klasifikon përgjigjet si më poshtë:

• Çdo përgjigje 2xx e shënon dorëzimin si të suksesshëm.
• Përgjigjet 408 Request Timeout, 429 Too Many Requests dhe 5xx janë dështime të përkohshme dhe mund të riprovohen.
• Dështimet e rrjetit që mund të jenë të përkohshme riprovohen.
• Ridrejtimet dhe përgjigjet e tjera 3xx nuk ndiqen dhe trajtohen si dështime përfundimtare.
• Përgjigjet e tjera 4xx trajtohen si dështime përfundimtare dhe nuk riprovohen.

Ktheni 200, 202 ose 204 vetëm kur ngjarja është pranuar në mënyrë të sigurt. Nëse përpunimi kërkon kohë, ruajeni fillimisht ngjarjen dhe ktheni një përgjigje suksesi para se të kryeni punën më të ngadaltë në mënyrë asinkrone.

Mos ktheni një ridrejtim në një URL tjetër webhook-u. Konfiguroni URL-në përfundimtare në Maildroppa.

Orari i riprovimeve automatike

Dorëzimet e prodhimit mund të bëjnë deri në shtatë përpjekje HTTP.

Pas një dështimi që mund të riprovohet, Maildroppa planifikon përpjekjen tjetër me këto vonesa:

1. Pas përpjekjes 1: 1 minutë
2. Pas përpjekjes 2: 5 minuta
3. Pas përpjekjes 3: 30 minuta
4. Pas përpjekjes 4: 2 orë
5. Pas përpjekjes 5: 12 orë
6. Pas përpjekjes 6: 24 orë

Nëse përpjekja 7 ende merr një dështim që mund të riprovohet, dorëzimi bëhet Dead dhe nuk planifikohet asnjë përpjekje tjetër automatike.

Orari matet nga përpjekjet individuale të dështuara. Koha aktuale e dorëzimit mund të jetë pak më e vonshme sepse dorëzimet përpunohen në mënyrë asinkrone dhe i nënshtrohen gjithashtu kufijve të mbrojtjes së sistemit.

Rregulloni problemin e përkohshëm të marrësit para kohës së shfaqur “Next retry” kur është e mundur. Nëse përpjekjet automatike kanë përfunduar, përdorni Replay pasi marrësi të jetë përsëri i shëndetshëm.

Kuptimi i Delivery history

Delivery history i përket endpoint-it të zgjedhur aktualisht. URL-ja e endpoint-it shfaqet në titullin e seksionit, në mënyrë që të konfirmoni cilin historik po shikoni.

Përdorni këto filtra:

• All — Shfaq dorëzimet e prodhimit dhe të testimit.
• Production — Shfaq vetëm dorëzimet e ngjarjeve të drejtpërdrejta.
• Test — Shfaq vetëm testet manuale.

Klikoni “Refresh” për të marrë gjendjen më të fundit. Historiku nuk ka nevojë të lihet i hapur ndërsa Maildroppa dërgon ose riprovon një dorëzim.

Faqja shfaq 50 dorëzimet më të fundit që përputhen me filtrin e zgjedhur.

Kolonat e dorëzimit

Çdo rresht përmban:

• Created — Kur u krijua rekordi i dorëzimit.
• State — Pending, Success, Failed ose Dead.
• HTTP — Statusi i përgjigjes, numri i përpjekjeve dhe kohëzgjatja, si dhe koha e riprovimit të ardhshëm kur aplikohet.
• Subscriber — Email-i i abonentit kur ngjarja lidhet me një abonent.
• Delivery — Lloji i ngjarjes, Event ID dhe Delivery ID.
• Actions — Replay kur dorëzimi është i përshtatshëm.

Nëse nuk u bë asnjë kërkesë HTTP, kolona HTTP shfaq “No HTTP attempt”. Kjo mund të ndodhë kur Maildroppa e refuzon kërkesën para dërgimit, për shembull sepse Signing secret mungon ose destinacioni i ruajtur nuk mund të përdoret më në mënyrë të sigurt.

Kur është e disponueshme, rreshti shfaq gjithashtu një Error dhe një Response excerpt të kthyer nga marrësi. Mos ktheni secret-e ose të dhëna personale të ndjeshme në trupin e përgjigjes së webhook-ut, sepse një pjesë e asaj përgjigjeje mund të shfaqet në regjistrin e dorëzimeve të llogarisë.

Gjendjet e dorëzimit

Pending do të thotë se dorëzimi po pret përpjekjen e parë ose një riprovim të planifikuar. “Next retry” shfaqet kur është planifikuar një përpjekje tjetër.

Success do të thotë se marrësi ktheu një përgjigje 2xx. Nuk kërkohet asnjë përpjekje tjetër automatike.

Failed do të thotë se dorëzimi përfundoi me një problem që nuk mund të riprovohet, u refuzua para një përpjekjeje HTTP ose u ndal para se të mund të dërgohej.

Dead do të thotë se u përdorën të gjitha përpjekjet automatike për një problem që mund të riprovohej pa marrë një përgjigje të suksesshme.

Ruajtja e historikut

Rekordet e dorëzimeve ruhen për një kohë të kufizuar:

• Dorëzimet e suksesshme të prodhimit: 30 ditë
• Dorëzimet e dështuara të prodhimit: 90 ditë
• Dorëzimet Dead të prodhimit: 90 ditë
• Dorëzimet e testimit: 30 ditë

Mbani regjistrat tuaj të integrimit kur ju nevojitet një historik më i gjatë auditimi. Ruani Event ID dhe Delivery ID, por shmangni ruajtjen e panevojshme të secret-eve.

Ridërgimi i një dorëzimi

Klikoni “Replay” kur një dorëzim prodhimi i përfunduar duhet të provohet përsëri.

Replay është i disponueshëm për dorëzimet e prodhimit në gjendjen Success, Failed ose Dead. Nuk është i disponueshëm ndërsa një dorëzim është Pending dhe dorëzimet e testimit nuk mund të ridërgohen.

Një ridërgim:

• Krijon një dorëzim të ri Pending.
• Krijon një Delivery ID të ri.
• Mban Event ID origjinal.
• Mban llojin origjinal të ngjarjes dhe payload-in JSON.
• Përdor URL-në origjinale të ruajtur të objektivit dhe snapshot-in e kokave të personalizuara.
• Përdor Signing secret aktual kur përgatitet kërkesa e re.

Replay nuk e rindërton payload-in nga të dhënat aktuale të abonentit. Ai ridërgon snapshot-in origjinal të ngjarjes. Kjo e bën ridërgimin të auditueshëm dhe parandalon ndryshimin e heshtur të kuptimit të një ngjarjeje historike.

Vetëm një ridërgim i të njëjtit dorëzim burimor mund të jetë Pending në të njëjtën kohë. Prisni derisa ai ridërgim të përfundojë para se të kërkoni një tjetër.

Sigurohuni që endpoint-i të jetë Active para ridërgimit. Nëse endpoint-i është joaktiv, ridërgimi në radhë nuk mund të dorëzohet me sukses.

Meqë një marrës mund ta ketë përfunduar veprimin e biznesit edhe kur Maildroppa nuk mori përgjigjen e suksesit, ridërgimi mund të prodhojë një kërkesë dublikatë. Dedublikimi me Event ID mbron sistemin e lidhur nga përsëritja e veprimit.

Redaktimi i një endpoint-i

Klikoni “Edit” për të ndryshuar URL-në, përzgjedhjen e ngjarjeve, kokat e personalizuara ose statusin aktiv.

Para ruajtjes:

1. Konfirmoni që URL-ja e re është tashmë e disponueshme.
2. Lërini bosh vlerat e ruajtura të kokave kur duhet të mbeten të pandryshuara.
3. Vendosni një vlerë të re për çdo kokë të riemërtuar.
4. Rishikoni përzgjedhjen e ngjarjeve që njoftimet e nevojshme të mos hiqen aksidentalisht.
5. Ruani dhe dërgoni një Test webhook të ri.

Mos harroni se dorëzimet në radhë ruajnë snapshot-in ekzistues të URL-së dhe kokave të personalizuara. Testoni konfigurimin e ri për dorëzimet e ardhshme dhe mos supozoni se ai ndryshon një kërkesë më të vjetër në radhë.

Çaktivizimi i një endpoint-i

Përdorni çelësin On/Off kur dëshironi të pezulloni një integrim pa fshirë konfigurimin dhe historikun e tij.

Kur një endpoint fiket:

• Ngjarjet e reja nuk vendosen më në radhë për të.
• Dorëzimet Pending që nuk janë marrë ende për dërgim shënohen Failed.
• Test çaktivizohet.
• Endpoint-i mbetet i disponueshëm për redaktim dhe aktivizim të mëvonshëm.

Një kërkesë që është tashmë në proces në momentin e çaktivizimit mund të përfundojë ende. Kontrolloni Delivery history pasi ta fikni endpoint-in nëse ky dallim ka rëndësi për integrimin tuaj.

Ngjarjet e humbura ndërsa endpoint-i është joaktiv nuk plotësohen kur e ndizni përsëri.

Fshirja e një endpoint-i

Klikoni “Delete” dhe konfirmoni paralajmërimin kur endpoint-i nuk duhet të ekzistojë më.

Fshirja e heq endpoint-in nga faqja, ndalon dorëzimet e ardhshme të ngjarjeve dhe dështon dorëzimet Pending që nuk janë marrë ende për dërgim.

Delete nuk është mënyrë për pezullim të përkohshëm. Përdorni çelësin On/Off kur mund t’ju nevojitet përsëri konfigurimi ose historiku i dukshëm.

Para fshirjes, regjistroni çdo Event ID ose Delivery ID që ju nevojitet ende për auditimin e integrimit.

Zgjidhja e problemeve

Endpoint-i nuk mund të ruhet

Kontrolloni që:

• URL-ja fillon me https://.
• URL-ja përdor hostname publik dhe portën 443.
• URL-ja nuk përmban variabla, të dhëna identifikimi ose fragment.
• Është zgjedhur të paktën një ngjarje.
• Çdo Custom header ka një emër unik dhe një vlerë.
• Kokat e rezervuara të Maildroppa-s dhe HTTP-së nuk përdoren si emra të personalizuar.

Test është i çaktivizuar

Test është i disponueshëm vetëm për një endpoint Active. Ndizeni endpoint-in ose redaktojeni dhe zgjidhni “Active”, më pas ruajeni para testimit.

Testi nuk tregon asnjë përpjekje HTTP

Gjeneroni një Signing secret nëse statusi është Missing. Kontrolloni gjithashtu nëse hostname-i i destinacionit është publik dhe ende zgjidhet saktë.

Një kërkesë mund të refuzohet para dërgimit kur secret-i, URL-ja, kokat e personalizuara ose kontrolli i sigurisë së destinacionit janë të pavlefshme.

Marrësi kthen 401 ose 403

Kontrolloni emrin e ruajtur të Custom header dhe kredencialin. Redaktoni endpoint-in dhe vendoseni përsëri vlerën nëse ajo ka ndryshuar.

Verifikoni gjithashtu që marrësi të mos ngatërrojë kredencialin e vet API me nënshkrimin e Maildroppa-s. Një kokë autorizimi e personalizuar dhe X-Maildroppa-Signature shërbejnë për qëllime të ndryshme dhe mund të kontrollohen në mënyrë të pavarur.

Marrësi kthen një ridrejtim

Maildroppa nuk ndjek ridrejtimet. Zëvendësoni URL-në e endpoint-it me URL-në përfundimtare publike HTTPS dhe testoni përsëri.

Nënshkrimi nuk përputhet

Konfirmoni që marrësi:

• Përdor Signing secret aktual.
• Përdor vlerën e saktë X-Maildroppa-Timestamp.
• Nënshkruan <timestamp>.<raw request body>.
• Përdor HMAC-SHA256 dhe dalje heksadecimale me shkronja të vogla.
• Krahason vlerën e plotë, përfshirë v1=.
• E kryen krahasimin para se analizimi JSON të ndryshojë trupin.

E njëjta ngjarje mbërrin më shumë se një herë

Kjo mund të ndodhë pas një ndërprerjeje rrjeti, riprovimi ose ridërgimi manual. Është normale që sistemet e dorëzimit të webhook-eve të ofrojnë dorëzim të paktën një herë, jo dorëzim saktësisht një herë.

Përdorni Event ID si çelës idempotence. Ktheni një përgjigje 2xx kur një Event ID i përpunuar më parë merret përsëri dhe nuk nevojitet asnjë veprim shtesë.

Një dorëzim është Pending

Shikoni “Next retry” në kolonën HTTP. Një 408, 429, 5xx ose dështim i përkohshëm i rrjetit që mund të riprovohet mbetet Pending deri në përpjekjen tjetër të planifikuar.

Klikoni “Refresh” pas kohës së riprovimit për të ngarkuar gjendjen më të fundit.

Një dorëzim është Dead

U përdorën të gjitha përpjekjet automatike. Rregulloni fillimisht marrësin, sigurohuni që endpoint-i të jetë Active, dërgoni një Test webhook dhe më pas përdorni Replay në dorëzimin e prodhimit.

Lista kontrolluese e rekomanduar për prodhimin

Para se të mbështeteni te një endpoint në prodhim, konfirmoni të gjitha sa vijon:

1. Marrësi përdor një URL të qëndrueshme publike HTTPS me certifikatë të vlefshme.
2. Signing secret ruhet jashtë kodit burimor.
3. Nënshkrimi kontrollohet kundrejt trupit të papërpunuar të pandryshuar.
4. Timestamp-et e vjetra refuzohen sipas një tolerance të dokumentuar.
5. Marrësi ruan dhe dedupliko Event ID-të.
6. Marrësi regjistron Event ID dhe Delivery ID për gjurmim.
7. Përpunimi i ngadaltë ndodh pasi ngjarja të jetë pranuar në mënyrë të qëndrueshme.
8. Një përgjigje 2xx kthehet vetëm për ngjarje të pranuara.
9. Kredencialet e personalizuara ruhen në koka dhe jo në URL.
10. Zgjidhen vetëm llojet e nevojshme të ngjarjeve.
11. Një Test webhook ka sukses dhe shfaqet saktë në Delivery history.
12. Monitorimi ju lajmëron kur dorëzimet e prodhimit fillojnë të kthejnë gabime.

Me këto masa mbrojtëse, faqja Webhooks ofron të dyja anët e një integrimi të besueshëm: dorëzim të sigurt të ngjarjeve në aplikacionin tuaj dhe një historik të qartë operacional brenda Maildroppa-s.