Konfiguriranje webhookova

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

Webhookovi omogućuju Maildroppi da obavijesti drugu aplikaciju kada se u vašem računu dogodi nešto važno.

Umjesto da više puta pitate Maildroppu je li pretplatnik izrađen, ažuriran, odjavljen ili mu je dodana oznaka, vaša aplikacija može primiti HTTPS zahtjev ubrzo nakon događaja.

Stranica Webhooks središnje je mjesto za ovu integraciju na razini računa. Možete izraditi više krajnjih točaka, odabrati događaje koje svaka krajnja točka prima, dodati zaglavlja za autentikaciju, testirati vezu, pregledati pokušaje isporuke i po potrebi ponovno reproducirati produkcijski događaj.

Kako funkcioniraju webhookovi računa

Webhook računa slijedi ovaj postupak:

1. U Maildroppi se dogodi događaj, primjerice izrada pretplatnika.
2. Maildroppa pronalazi svaku aktivnu krajnju točku koja je pretplaćena na taj događaj.
3. Maildroppa izrađuje jednu isporuku za svaku odgovarajuću krajnju točku.
4. JSON sadržaj potpisuje tajnom za potpisivanje webhookova vašeg računa.
5. Maildroppa šalje HTTPS zahtjev POST na spremljeni URL krajnje točke.
6. Vaša krajnja točka provjerava potpis, pohranjuje ili obrađuje događaj te vraća HTTP odgovor.
7. Maildroppa bilježi rezultat u Povijesti isporuke i automatski ponovno pokušava privremene neuspjele isporuke.

Ako je više krajnjih točaka pretplaćeno na isti događaj, svaka krajnja točka prima vlastitu isporuku. Poslovni događaj za sve njih ima isti ID događaja, dok svaka isporuka ima vlastiti ID isporuke.

Webhookovi računa razlikuju se od koraka „Send a webhook” unutar automatizacije. Webhookovi računa osluškuju odabrane događaje računa u cijeloj Maildroppi. Webhook automatizacije šalje se samo kada pretplatnik dođe do tog konkretnog koraka. Oba koriste tajnu za potpisivanje webhookova računa, pa promjena tajne utječe na svaki odlazni prijamnik webhookova koji provjerava Maildroppa potpise.

Otvaranje stranice Webhooks

Otvorite „Settings”, proširite „Developers” i odaberite „Webhooks”.

Stranica sadrži tri glavna područja:

• Tajna za potpisivanje
• Krajnje točke
• Povijest isporuke za odabranu krajnju točku

Kada imate više od jedne krajnje točke, odaberite redak krajnje točke kako biste prikazali njezinu Povijest isporuke. Ako nijednu niste izričito odabrali, Maildroppa prikazuje povijest prve krajnje točke na popisu.

Prije izrade krajnje točke

Pripremite prijamnik na svom poslužitelju prije konfiguriranja Maildroppe. Prijamnik bi trebao:

• Biti dostupan putem javnog HTTPS URL-a.
• Prihvaćati zahtjeve POST s tijelom application/json.
• Sačuvati izvorno tijelo zahtjeva dok se ne provjeri Maildroppa potpis.
• Vratiti status 2xx tek nakon što je događaj sigurno prihvaćen.
• Idempotentno obrađivati ponovljene isporuke koristeći ID događaja.
• Brzo odgovoriti umjesto da tijekom zahtjeva obavlja spore operacije.

Pouzdan je obrazac provjeriti zahtjev, pohraniti ID događaja i sadržaj u trajni red čekanja ili bazu podataka, vratiti 200 ili 204 te naknadno obraditi poslovnu radnju.

Nemojte razvojno računalo, adresu lokalne mreže ili nezaštićenu skriptu izložiti kao produkcijski prijamnik webhookova. Maildroppa prihvaća samo javna HTTPS odredišta i ponovno provjerava odredište prilikom slanja isporuke.

1. korak: generiranje tajne za potpisivanje

---

Svaki Maildroppa webhook zahtjev je potpisan. Vaš prijamnik koristi tajnu za potpisivanje kako bi provjerio da je zahtjev izradila Maildroppa i da tijelo nije izmijenjeno tijekom prijenosa.

Na vrhu stranice ploča Tajna za potpisivanje prikazuje jedno od ovih stanja:

• Nedostaje — Tajna za potpisivanje još ne postoji.
• Spremno — Tajna za potpisivanje je konfigurirana.
• Učitavanje — Maildroppa dohvaća trenutačni status.

Kliknite „Generate secret” kada je status Nedostaje.

Maildroppa odmah prikazuje novu tajnu. Počinje s whsec_. Kliknite „Copy” i pohranite je u upravitelj tajni ili zaštićenu konfiguraciju okruženja koju koristi vaš prijamnik.

Cijela vrijednost prikazuje se samo neposredno nakon generiranja ili rotiranja. Kada ponovno učitate stranicu ili je napustite, Maildroppa prikazuje samo da tajna postoji i kada je posljednji put ažurirana. Spremljenu tajnu više ne otkriva.

Ako izgubite tajnu

Ako prijamnik više nema trenutačnu tajnu, kliknite „Rotate secret” i spremite novoprikazanu vrijednost.

Rotiranjem se prethodna tajna odmah zamjenjuje. Maildroppa ne zadržava obje vrijednosti tijekom prijelaznog razdoblja. Ažurirajte svaki prijamnik koji koristi ovu tajnu računa prije slanja novih testova ili oslanjanja na produkcijske isporuke.

Nove isporuke, zakazani ponovni pokušaji, testovi i ponovne reprodukcije potpisuju se trenutačnom tajnom u trenutku HTTP zahtjeva. To znači da se isporuka izrađena prije rotiranja i dalje može potpisati novom tajnom ako se pokuša poslati nakon rotiranja.

Tretirajte tajnu kao lozinku

Ne stavljajte tajnu za potpisivanje u kôd preglednika, javni repozitorij, URL, stranicu s pogreškom ili običan zapisnik aplikacije.

Tajna je potrebna samo prijamniku na strani poslužitelja. Ako smatrate da je otkrivena, odmah je rotirajte i ažurirajte sve prijamnike.

Provjera potpisa webhooka

Svaki zahtjev sadrži ova Maildroppa zaglavlja:

• X-Maildroppa-Event-Id — Identificira poslovni događaj.
• X-Maildroppa-Delivery-Id — Identificira ovu konkretnu isporuku.
• X-Maildroppa-Timestamp — Vrijeme potpisivanja u Unix sekundama.
• X-Maildroppa-Signature — HMAC potpis s verzijom.

Maildroppa također šalje:

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

Potpis ima ovaj format:

v1=<lowercase hexadecimal HMAC>

Maildroppa ga izrađuje pomoću HMAC-SHA256. Potpisani sadržaj čine vremenska oznaka, točka i točno izvorno JSON tijelo zahtjeva:

<timestamp>.<raw request body>

Kao HMAC ključ upotrijebite tajnu za potpisivanje.

Sljedeći primjer u Node.jsu prikazuje osnovni korak provjere. rawBody mora sadržavati izvorne bajtove zahtjeva, a ne JSON koji je već raščlanjen i ponovno serijaliziran.

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

Nakon provjere potpisa usporedite i vremensku oznaku s vremenom svojeg poslužitelja. Odbijte zahtjeve izvan kratke tolerancije odabrane za vašu infrastrukturu, primjerice pet minuta. Time se smanjuje rizik da se zarobljeni valjani zahtjev ponovno reproducira mnogo kasnije.

JSON raščlanite i obradite tek nakon što su obje provjere uspješno prošle.

Uobičajeni uzroci pogrešaka potpisa

Potpis najčešće ne uspije iz jednog od ovih razloga:

• Prijamnik nakon rotiranja koristi staru tajnu.
• Međuprogramska oprema je raščlanila ili izmijenila JSON prije izračuna potpisa.
• Prijamnik potpisuje samo tijelo i izostavlja <timestamp>..
• Vremenska oznaka tretira se kao formatirani datum umjesto točne vrijednosti zaglavlja.
• Prefiks v1= izostavljen je iz usporedbe.
• Izračunati HMAC kodiran je drugačije umjesto malim heksadecimalnim slovima.

Kada provjera ne uspije, zabilježite ID događaja i ID isporuke, ali nikada nemojte zapisivati tajnu za potpisivanje ni osjetljive vrijednosti prilagođenih zaglavlja.

2. korak: dodavanje krajnje točke

---

Kliknite „Add endpoint” u odjeljku Krajnje točke.

Uređivač se sastoji od četiri dijela:

• URL krajnje točke
• Događaji
• Prilagođena zaglavlja
• Aktivni status

Nove krajnje točke počinju kao aktivne, a svi događaji prikazani u uređivaču u početku su odabrani. Pregledajte odabir prije spremanja kako bi prijamnik primao samo obavijesti koje mu zaista trebaju.

Konfiguriranje URL-a krajnje točke

Unesite potpuni javni URL koji treba primati Maildroppa zahtjeve, primjerice:

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

URL mora ispunjavati ove zahtjeve:

• Mora koristiti https://.
• Mora sadržavati valjano javno ime hosta.
• Može imati najviše 2.048 znakova.
• Ne smije sadržavati varijable predloška s { ili }.
• Ne smije sadržavati korisničko ime ili lozinku prije imena hosta.
• Ne smije sadržavati fragment URL-a koji počinje znakom #.
• Mora koristiti standardni HTTPS port 443.
• Ne smije koristiti localhost, sirovu IP adresu ni ime hosta koje se razrješava na blokiranu privatnu ili rezerviranu mrežu.

Parametri upita su podržani, ali u URL nemojte stavljati API ključeve ni druge tajne. URL-ovi su vidljivi na popisu krajnjih točaka i u podacima o isporuci. Za vjerodajnice umjesto toga upotrijebite prilagođeno zaglavlje.

Maildroppa ne slijedi preusmjeravanja. Spremite konačno HTTPS odredište, a ne URL koji vraća 301, 302, 307 ili 308.

Ime hosta odredišta ponovno se razrješava prije slanja. Ime hosta koje se kasnije razriješi na privatnu ili blokiranu adresu odbija se čak i ako je bilo valjano pri spremanju krajnje točke.

Odabir događaja

Odaberite barem jedan događaj. Krajnja točka prima samo vrste događaja odabrane u njezinu uređivaču.

Stranica nudi ove mogućnosti događaja:

Pretplatnik izrađen — subscriber.created

Šalje se kada se u računu Maildroppa izradi pretplatnik.

Ovaj događaj upotrijebite za izradu odgovarajućeg kontakta u CRM-u, platformi za korisničke podatke, internoj bazi podataka ili drugom sustavu koji vodi računa o dopuštenjima.

Ovaj događaj nemojte tumačiti kao dokaz da je svaka prijava završila dvostruku potvrdu (Double Opt-in). Status pretplatnika u sadržaju opisuje trenutačno stanje.

Pretplatnik ažuriran — subscriber.updated

Šalje se kada se promijene ugrađeni podaci pretplatnika ili vrijednosti prilagođenih polja.

Potpuni objekt pretplatnika u sadržaju koristite kao trenutačni prikaz pretplatnika u Maildroppi. Nemojte pretpostavljati da se promijenilo samo jedno određeno svojstvo.

Dodjeljivanje i uklanjanje oznaka imaju vlastite vrste događaja kako bi se mogli zasebno obrađivati.

Pretplatnik odjavljen — subscriber.unsubscribed

Šalje se kada pretplatnik prelazi u stanje odjave putem radnje odjave.

Ovaj događaj upotrijebite za isključivanje kontakta u povezanim sustavima. Nemojte automatski ponovno prijaviti osobu zato što je drugi sustav i dalje označava kao aktivan kontakt.

Oznaka dodana — subscriber.tag_added

Šalje se kada se pretplatniku dodijeli oznaka.

Sadržaj sadrži pretplatnika i oznaku uključene u tu konkretnu promjenu.

Oznaka uklonjena — subscriber.tag_removed

Šalje se kada se pretplatniku ukloni oznaka.

Sadržaj sadrži ažuriranog pretplatnika i uklonjenu oznaku. Uklonjena oznaka navedena je zasebno iako više nije prisutna u trenutačnom polju tags pretplatnika.

Obrazac poslan — form.submitted

Šalje se kada posjetitelj pošalje Maildroppa obrazac za prijavu.

Tretirajte ovo kao signal slanja obrasca, a ne kao potvrdu da je dvostruka potvrda (Double Opt-in) dovršena. Svaki tijek rada koji zahtijeva potvrđenu pretplatu mora i dalje poštovati trenutačni status pretplatnika i postupak potvrde.

Koristite zasebne krajnje točke kada se odgovornosti razlikuju

Različite događaje možete slati različitim sustavima. Na primjer:

• Šaljite događaje pretplatnika i oznaka u CRM.
• Šaljite događaje odjave usluzi za isključivanje.
• Šaljite događaje slanja obrazaca analitičkom sustavu.

Zasebne krajnje točke smanjuju nepotreban promet i olakšavaju dijagnosticiranje pogrešaka. Svaka krajnja točka ima vlastiti odabir događaja, URL, prilagođena zaglavlja, aktivni status, testove i Povijest isporuke.

Dodavanje prilagođenih zaglavlja

Prilagođena zaglavlja nisu obavezna. Koristite ih kada prijamnik zahtijeva API ključ, nosivi token, identifikator klijenta ili drugo fiksno zaglavlje.

Kliknite „Add header”, a zatim unesite naziv zaglavlja i vrijednost zaglavlja. Prikladni primjeri uključuju:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Možete dodati najviše 20 prilagođenih zaglavlja.

Nazivi zaglavlja:

• Obavezni su.
• Mogu sadržavati najviše 128 znakova.
• Moraju koristiti valjane znakove za naziv HTTP zaglavlja.
• Moraju biti jedinstveni neovisno o velikim i malim slovima.

Vrijednosti zaglavlja:

• Obavezne su.
• Mogu sadržavati najviše 2.000 znakova.
• Ne smiju sadržavati prijelome redaka.

Sljedeći nazivi rezervirani su i ne mogu se zamijeniti prilagođenim zaglavljem:

• Content-Type
• Content-Length
• Host
• User-Agent
• Bilo koji naziv koji počinje s X-Maildroppa-

Time se sprječava da prilagođena vrijednost zamijeni Maildroppa zaglavlja za isporuku i potpis.

Kako se pohranjuju tajne vrijednosti zaglavlja

Maildroppa šifrira vrijednosti prilagođenih zaglavlja prije pohrane. Spremljene vrijednosti ne vraćaju se pregledniku u čitljivom obliku.

Kada poslije uređujete krajnju točku, polje vrijednosti prikazuje „Stored value kept”. Ostavite ga praznim kada postojeća tajna treba ostati nepromijenjena. Unesite novu vrijednost da biste je zamijenili.

Ako promijenite naziv zaglavlja, ponovno unesite vrijednost. Maildroppa zadržava spremljenu tajnu samo dok njezin izvorni naziv zaglavlja ostaje nepromijenjen.

Uklanjanjem retka zaglavlja to se zaglavlje uklanja iz budućih isporuka nakon spremanja krajnje točke.

Vrijednosti prilagođenih zaglavlja tretiraju se kao osjetljive u pohranjenim podacima zahtjeva. U Povijesti isporuke maskirane su, a ne prikazane.

Postavljanje krajnje točke na aktivnu ili neaktivnu

Ostavite odabrano „Active” kada je krajnja točka spremna odmah primati događaje.

Poništite odabir kada konfiguraciju želite spremiti bez pokretanja isporuka. Krajnju točku poslije možete aktivirati s popisa krajnjih točaka.

Neaktivna krajnja točka:

• Ne prima novonastale događaje.
• Ne može slati testni webhook.
• Ostaje vidljiva i može se uređivati.
• Zadržava dostupnu postojeću Povijest isporuke.

Aktiviranjem krajnje točke ne popunjavaju se naknadno događaji koji su se dogodili dok je bila neaktivna.

Kliknite „Save” kada su URL, odabir događaja, zaglavlja i status ispravni.

Razumijevanje popisa krajnjih točaka

Svaki redak krajnje točke prikazuje:

• Odredišni URL.
• Oznaku Active ili Inactive.
• Pretplaćene vrste događaja.
• Broj prilagođenih zaglavlja.
• Vrijeme posljednjeg ažuriranja krajnje točke.

Dostupne radnje su:

• On/Off — Aktivira ili deaktivira krajnju točku.
• Test — Šalje jedan neposredni testni zahtjev aktivnoj krajnjoj točki.
• Edit — Mijenja URL, događaje, zaglavlja ili aktivni status.
• Delete — Trajno uklanja konfiguraciju krajnje točke nakon potvrde.

Odaberite glavni dio retka kako biste ispod popisa otvorili Povijest isporuke te krajnje točke.

Kako spremljene promjene utječu na postojeće isporuke

Događaj računa stvara isporuku sa snimkom URL-a krajnje točke, sadržaja i prilagođenih zaglavlja u tom trenutku.

Uređivanje URL-a ili prilagođenih zaglavlja utječe na novostvorene isporuke. Isporuka koja je već u redu čekanja zadržava izvorno odredište i spremljenu konfiguraciju zaglavlja.

Promjena odabranih događaja također utječe samo na događaje koji se dogode nakon toga. Maildroppa ne stvara retroaktivne isporuke za vrste događaja koje nisu bile odabrane kada se događaj dogodio.

Tajna za potpisivanje je drugačija: očitava se kada se priprema HTTP zahtjev. Stoga isporuka na čekanju ili ponovna reprodukcija može upotrijebiti novorotiranu tajnu za potpisivanje čak i kada su njezin sadržaj i snimka krajnje točke izrađeni ranije.

Testiranje krajnje točke

Kliknite „Test” na aktivnoj krajnjoj točki nakon što su prijamnik i tajna za potpisivanje spremni.

Maildroppa odmah šalje jedan potpisani zahtjev koristeći spremljeni URL krajnje točke i spremljena prilagođena zaglavlja. Nespremljene promjene u otvorenom uređivaču nisu dio testa.

Testni sadržaj koristi vrstu događaja webhook.test i postavlja livemode na false:

{
  "id": "evt_test_example",
  "type": "webhook.test",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": false,
  "data": {
    "message": "This is a test webhook from Maildroppa."
  }
}

Generirani ID-ovi i vremenska oznaka razlikuju se za svaki stvarni test.

Test izvodi točno jedan HTTP pokušaj. Testne isporuke ne stavljaju se na raspored ponovnih pokušaja produkcije i ne mogu se ponovno reproducirati.

Nakon završetka zahtjeva ploča s rezultatom prikazuje:

• Uspješan test ili neuspješan test
• ID događaja
• HTTP status, kada je odgovor primljen
• Trajanje
• ID isporuke
• Informacije o pogrešci, kada su dostupne
• Izvadak odgovora, kada je prijamnik vratio tijelo

Test se također pojavljuje u Povijesti isporuke s oznakom Test. Upotrijebite filtar „Test” kako biste prikazali samo testne zahtjeve.

Razumijevanje produkcijskog sadržaja

Produkcijski događaji računa koriste zajedničku JSON omotnicu:

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

Svojstva najviše razine znače:

• id — ID događaja. Podudara se s X-Maildroppa-Event-Id.
• type — Ključ događaja odabran u uređivaču krajnje točke.
• schema_version — Verzija sheme sadržaja. Koristite je pri odlučivanju o načinu raščlambe događaja.
• created_at — Vrijeme izrade sadržaja događaja, u UTC-u.
• livemode — true za produkcijske događaje i false za testne događaje.
• data — Sadržaj specifičan za događaj.

Usmjeravajte događaje prema točnoj vrijednosti type. Zanemarite dodatna svojstva koja vašoj integraciji nisu potrebna kako kompatibilna proširenja sadržaja ne bi prekinula rad prijamnika.

Sadržaj događaja pretplatnika

Događaji pretplatnika sadrže trenutačni prikaz pretplatnika unutar 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 i tags polja su nizovi. Mogu biti prazni. Svojstvo pretplatnika može također biti null kada vrijednost ne postoji, stoga vaš prijamnik treba slijediti shemu sadržaja umjesto pretpostavljati da je svaka neobavezna vrijednost profila prisutna.

Sadržaj događaja oznake

Događaji oznaka sadrže i pretplatnika i oznaku koja je uzrokovala događaj:

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

Za subscriber.tag_removed, data.tag i dalje identificira uklonjenu oznaku iako je trenutačni niz tags pretplatnika više ne sadrži.

ID-ovi događaja, ID-ovi isporuke i idempotentnost

ID događaja i ID isporuke imaju različite svrhe.

ID događaja

ID događaja identificira poslovni događaj. Pojavljuje se u:

• Svojstvu id na najvišoj razini sadržaja.
• Zaglavlju zahtjeva X-Maildroppa-Event-Id.
• Povijesti isporuke.

Isti događaj može se poslati na više pretplaćenih krajnjih točaka. Te isporuke dijele ID događaja.

Ponovni pokušaji i ručne ponovne reprodukcije također zadržavaju izvorni ID događaja. Pohranite obrađene ID-ove događaja i poslovnu radnju učinite idempotentnom kako ponovljeni zahtjev ne bi izradio duplicirane kontakte, ponovio nepovratnu radnju ili dvaput primijenio istu promjenu.

ID isporuke

ID isporuke identificira jedan zapis isporuke. Pojavljuje se u:

• Zaglavlju zahtjeva X-Maildroppa-Delivery-Id.
• Povijesti isporuke.

Svaka isporuka krajnjoj točki ima vlastiti ID isporuke. Ručna ponovna reprodukcija stvara novi ID isporuke, a zadržava izvorni ID događaja.

ID isporuke koristite za tehničko praćenje i podršku. ID događaja koristite za deduplikaciju na poslovnoj razini.

Vraćanje ispravnog HTTP odgovora

Maildroppa klasificira odgovore na sljedeći način:

• Svaki odgovor 2xx označava isporuku uspješnom.
• Odgovori 408 Request Timeout, 429 Too Many Requests i 5xx privremene su pogreške te se mogu ponovno pokušati.
• Mrežne pogreške koje mogu biti privremene ponovno se pokušavaju.
• Preusmjeravanja i drugi odgovori 3xx ne slijede se i tretiraju se kao konačne pogreške.
• Drugi odgovori 4xx tretiraju se kao konačne pogreške i ne pokušavaju se ponovno.

Vratite 200, 202 ili 204 samo kada je događaj sigurno prihvaćen. Ako obrada traje, najprije pohranite događaj i vratite uspješan odgovor, a zatim sporiji posao obavite asinkrono.

Ne vraćajte preusmjeravanje na drugi URL webhooka. Umjesto toga u Maildroppi konfigurirajte konačni URL.

Automatski raspored ponovnih pokušaja

Produkcijske isporuke mogu imati do sedam HTTP pokušaja.

Nakon neuspjeha koji se može ponovno pokušati, Maildroppa zakazuje sljedeći pokušaj s ovim odgodama:

1. Nakon pokušaja 1: 1 minuta
2. Nakon pokušaja 2: 5 minuta
3. Nakon pokušaja 3: 30 minuta
4. Nakon pokušaja 4: 2 sata
5. Nakon pokušaja 5: 12 sati
6. Nakon pokušaja 6: 24 sata

Ako se pri pokušaju 7 i dalje primi pogreška koja se može ponovno pokušati, isporuka prelazi u stanje Dead i ne zakazuje se daljnji automatski pokušaj.

Raspored se mjeri od pojedinačnih neuspjelih pokušaja. Stvarno vrijeme isporuke može biti nešto kasnije jer se isporuke obrađuju asinkrono i podliježu i ograničenjima zaštite sustava.

Kad god je moguće, privremeni problem prijamnika riješite prije prikazanog vremena „Next retry”. Ako su automatski pokušaji završili, upotrijebite Replay nakon što prijamnik ponovno bude ispravan.

Razumijevanje Povijesti isporuke

Povijest isporuke pripada trenutačno odabranoj krajnjoj točki. URL krajnje točke pojavljuje se u zaglavlju odjeljka kako biste mogli potvrditi čiju povijest pregledavate.

Koristite ove filtre:

• All — Prikazuje produkcijske i testne isporuke.
• Production — Prikazuje samo isporuke živih događaja.
• Test — Prikazuje samo ručne testove.

Kliknite „Refresh” kako biste dohvatili najnovije stanje. Povijest ne mora ostati otvorena dok Maildroppa šalje ili ponovno pokušava isporuku.

Stranica prikazuje najnovijih 50 isporuka koje odgovaraju odabranom filtru.

Stupci isporuke

Svaki redak sadrži:

• Created — Kada je zapis isporuke izrađen.
• State — Pending, Success, Failed ili Dead.
• HTTP — Status odgovora, broj pokušaja i trajanje te vrijeme sljedećeg ponovnog pokušaja kada je primjenjivo.
• Subscriber — E-adresa pretplatnika kada je događaj povezan s pretplatnikom.
• Delivery — Vrsta događaja, ID događaja i ID isporuke.
• Actions — Replay kada je isporuka podobna za to.

Ako nije poslan nijedan HTTP zahtjev, stupac HTTP prikazuje „No HTTP attempt”. To se može dogoditi kada Maildroppa odbije zahtjev prije slanja, primjerice zato što nedostaje tajna za potpisivanje ili se spremljeno odredište više ne može sigurno koristiti.

Kada su dostupni, redak prikazuje i pogrešku te izvadak odgovora koji je vratio prijamnik. U tijelu odgovora webhooka nemojte vraćati tajne ni osjetljive osobne podatke jer se dio tog odgovora može pojaviti u zapisniku isporuke računa.

Stanja isporuke

Pending znači da isporuka čeka prvi pokušaj ili zakazani ponovni pokušaj. „Next retry” prikazuje se kada je zakazan novi pokušaj.

Success znači da je prijamnik vratio odgovor 2xx. Nije potreban daljnji automatski pokušaj.

Failed znači da je isporuka završila problemom koji se ne može ponovno pokušati, da je odbijena prije HTTP pokušaja ili da je zaustavljena prije slanja.

Dead znači da su iskorišteni svi automatski pokušaji za problem koji se može ponovno pokušati, a uspješan odgovor nije primljen.

Zadržavanje povijesti

Zapisi isporuke zadržavaju se ograničeno vrijeme:

• Uspješne produkcijske isporuke: 30 dana
• Neuspješne produkcijske isporuke: 90 dana
• Produkcijske isporuke u stanju Dead: 90 dana
• Testne isporuke: 30 dana

Kada vam je potrebna dulja povijest revizije, vodite vlastite zapisnike integracije. Pohranjujte ID-ove događaja i ID-ove isporuke, ali izbjegavajte nepotrebnu pohranu tajni.

Ponovna reprodukcija isporuke

Kliknite „Replay” kada dovršenu produkcijsku isporuku treba ponovno pokušati poslati.

Replay je dostupan za produkcijske isporuke u stanju Success, Failed ili Dead. Nije dostupan dok je isporuka u stanju Pending, a testne se isporuke ne mogu ponovno reproducirati.

Ponovna reprodukcija:

• Stvara novu isporuku u stanju Pending.
• Stvara novi ID isporuke.
• Zadržava izvorni ID događaja.
• Zadržava izvornu vrstu događaja i JSON sadržaj.
• Koristi izvornu spremljenu ciljnu adresu i snimku prilagođenih zaglavlja.
• Koristi trenutačnu tajnu za potpisivanje kada se priprema novi zahtjev.

Ponovna reprodukcija ne izrađuje sadržaj ponovno na temelju trenutačnih podataka pretplatnika. Ponovno šalje izvornu snimku događaja. Time se omogućuje revizija ponovne reprodukcije i sprječava da povijesni događaj neprimjetno promijeni značenje.

Istodobno može biti Pending samo jedna ponovna reprodukcija iste izvorne isporuke. Pričekajte da ta ponovna reprodukcija završi prije zahtjeva za novom.

Prije ponovne reprodukcije provjerite je li krajnja točka aktivna. Ako je neaktivna, stavljena ponovna reprodukcija ne može se uspješno isporučiti.

Budući da je prijamnik možda dovršio poslovnu radnju čak i kada Maildroppa nije primila njegov uspješan odgovor, ponovna reprodukcija može proizvesti duplicirani zahtjev. Deduplikacija prema ID-u događaja štiti povezani sustav od ponavljanja radnje.

Uređivanje krajnje točke

Kliknite „Edit” kako biste promijenili URL, odabir događaja, prilagođena zaglavlja ili aktivni status.

Prije spremanja:

1. Potvrdite da je novi URL već dostupan.
2. Ostavite spremljene vrijednosti zaglavlja praznima kada trebaju ostati nepromijenjene.
3. Unesite novu vrijednost za svako preimenovano zaglavlje.
4. Pregledajte odabir događaja kako slučajno ne biste uklonili potrebne obavijesti.
5. Spremite i pošaljite novi testni webhook.

Imajte na umu da isporuke u redu čekanja zadržavaju postojeći URL i snimku prilagođenih zaglavlja. Testirajte novu konfiguraciju za buduće isporuke umjesto pretpostavke da mijenja stariji zahtjev u redu čekanja.

Deaktiviranje krajnje točke

Upotrijebite prekidač On/Off kada želite pauzirati integraciju bez brisanja njezine konfiguracije i povijesti.

Kada se krajnja točka isključi:

• Novi se događaji više ne stavljaju u red čekanja za nju.
• Isporuke na čekanju koje još nisu preuzete za slanje označavaju se kao Failed.
• Test je onemogućen.
• Krajnja točka ostaje dostupna za uređivanje i kasniju aktivaciju.

Zahtjev koji je već u tijeku u trenutku deaktivacije i dalje se može završiti. Nakon isključivanja krajnje točke provjerite Povijest isporuke ako je ta razlika važna za vašu integraciju.

Događaji propušteni dok je krajnja točka neaktivna ne popunjavaju se naknadno kada je ponovno uključite.

Brisanje krajnje točke

Kliknite „Delete” i potvrdite upozorenje kada krajnja točka više ne treba postojati.

Brisanjem se krajnja točka uklanja sa stranice, zaustavljaju se buduće isporuke događaja i neuspješnima se označavaju isporuke na čekanju koje još nisu preuzete za slanje.

Delete nije način za privremenu pauzu. Upotrijebite prekidač On/Off kada bi vam konfiguracija ili vidljiva povijest ponovno mogle zatrebati.

Prije brisanja zabilježite sve ID-ove događaja ili ID-ove isporuke koji su vam još potrebni za reviziju integracije.

Otklanjanje poteškoća

Krajnju točku nije moguće spremiti

Provjerite sljedeće:

• URL počinje s https://.
• URL koristi javno ime hosta i port 443.
• URL ne sadrži varijable, podatke za prijavu ni fragment.
• Odabran je barem jedan događaj.
• Svako prilagođeno zaglavlje ima jedinstven naziv i vrijednost.
• Rezervirani Maildroppa i HTTP nazivi zaglavlja ne koriste se kao prilagođeni nazivi.

Test je onemogućen

Test je dostupan samo za aktivnu krajnju točku. Uključite krajnju točku ili je uredite i odaberite „Active”, a zatim je spremite prije testiranja.

Test ne prikazuje HTTP pokušaj

Generirajte tajnu za potpisivanje ako je status Nedostaje. Također provjerite je li odredišni hostname javan i razrješava li se i dalje ispravno.

Zahtjev može biti odbijen prije slanja kada su tajna, URL, prilagođena zaglavlja ili sigurnosna provjera odredišta nevaljani.

Prijamnik vraća 401 ili 403

Provjerite spremljeni naziv prilagođenog zaglavlja i vjerodajnicu. Uredite krajnju točku i ponovno unesite vrijednost ako se promijenila.

Također provjerite da prijamnik ne miješa vlastitu API vjerodajnicu s Maildroppa potpisom. Prilagođeno autorizacijsko zaglavlje i X-Maildroppa-Signature imaju različite svrhe i mogu se provjeravati neovisno.

Prijamnik vraća preusmjeravanje

Maildroppa ne slijedi preusmjeravanja. Zamijenite URL krajnje točke konačnim javnim HTTPS URL-om i ponovno testirajte.

Potpis se ne podudara

Potvrdite da prijamnik:

• Koristi trenutačnu tajnu za potpisivanje.
• Koristi točnu vrijednost X-Maildroppa-Timestamp.
• Potpisuje <timestamp>.<raw request body>.
• Koristi HMAC-SHA256 i izlaz u malim heksadecimalnim slovima.
• Uspoređuje cijelu vrijednost koja uključuje v1=.
• Usporedbu obavlja prije nego što raščlamba JSON-a promijeni tijelo.

Isti događaj stiže više puta

To se može dogoditi nakon prekida mreže, ponovnog pokušaja ili ručne ponovne reprodukcije. Uobičajeno je da sustavi za isporuku webhookova pružaju isporuku najmanje jednom, a ne točno jednom.

ID događaja koristite kao idempotencijski ključ. Vratite odgovor 2xx kada ponovno primite već obrađeni ID događaja i nije potrebna dodatna radnja.

Isporuka je na čekanju

Pogledajte „Next retry” u stupcu HTTP. Ponovljiva pogreška 408, 429, 5xx ili privremeni mrežni neuspjeh ostaje u stanju Pending do sljedećeg zakazanog pokušaja.

Kliknite „Refresh” nakon vremena ponovnog pokušaja kako biste učitali najnovije stanje.

Isporuka je u stanju Dead

Iskorišteni su svi automatski pokušaji. Najprije popravite prijamnik, provjerite je li krajnja točka aktivna, pošaljite testni webhook, a zatim na produkcijskoj isporuci upotrijebite Replay.

Preporučeni kontrolni popis za produkciju

Prije oslanjanja na krajnju točku u produkciji potvrdite sve sljedeće:

1. Prijamnik koristi stabilan javni HTTPS URL s valjanim certifikatom.
2. Tajna za potpisivanje pohranjena je izvan izvornog koda.
3. Potpis se provjerava prema neizmijenjenom izvornom tijelu.
4. Stare vremenske oznake odbijaju se prema dokumentiranoj toleranciji.
5. Prijamnik pohranjuje i deduplicira ID-ove događaja.
6. Prijamnik bilježi ID-ove događaja i ID-ove isporuke radi praćenja.
7. Spora obrada odvija se nakon trajnog prihvaćanja događaja.
8. Odgovor 2xx vraća se samo za prihvaćene događaje.
9. Prilagođene vjerodajnice pohranjuju se u zaglavljima, a ne u URL-u.
10. Odabrane su samo potrebne vrste događaja.
11. Testni webhook uspješan je i ispravno se pojavljuje u Povijesti isporuke.
12. Nadzor vas upozorava kada produkcijske isporuke počnu vraćati pogreške.

Uz ove zaštitne mjere stranica Webhooks pruža obje strane pouzdane integracije: sigurnu isporuku događaja vašoj aplikaciji i jasan operativni pregled unutar Maildroppe.