Webhookek konfigurálása

Published: 2026. július 16. · Last updated: 2026. július 21. · By Marcus Biel

A webhookok lehetővé teszik, hogy a Maildroppa értesítsen egy másik alkalmazást, amikor valami fontos történik a fiókjában.

Ahelyett, hogy folyamatosan megkérdezné a Maildroppát, hogy létrehoztak, frissítettek, leiratkoztattak-e egy feliratkozót, vagy hozzárendeltek-e hozzá egy címkét, az alkalmazása röviddel az esemény bekövetkezése után HTTPS-kérést fogadhat.

A Webhooks oldal a fiókszintű integráció központi helye. Több végpontot hozhat létre, kiválaszthatja az egyes végpontok által fogadott eseményeket, hitelesítési fejléceket adhat hozzá, tesztelheti a kapcsolatot, megtekintheti a kézbesítési kísérleteket, és szükség esetén újra lejátszhat egy éles eseményt.

Hogyan működnek a fiókszintű webhookok

Egy fiókszintű webhook folyamata:

1. Esemény történik a Maildroppában, például létrehoznak egy feliratkozót.
2. A Maildroppa megkeresi az összes aktív végpontot, amely fel van iratkozva az adott eseményre.
3. A Maildroppa minden egyező végponthoz létrehoz egy kézbesítést.
4. A JSON-törzs aláírása a fiók webhook-aláírási titkával történik.
5. A Maildroppa HTTPS POST kérést küld a mentett végpont-URL-re.
6. A végpont ellenőrzi az aláírást, tárolja vagy feldolgozza az eseményt, majd HTTP-választ küld.
7. A Maildroppa rögzíti az eredményt a Kézbesítési előzményekben, és automatikusan újrapróbálkozik az átmeneti hibák esetén.

Ha több végpont is fel van iratkozva ugyanarra az eseményre, minden végpont saját kézbesítést kap. Az üzleti esemény mindegyiknél ugyanazzal az Eseményazonosítóval rendelkezik, miközben minden kézbesítésnek saját Kézbesítésazonosítója van.

A fiókszintű webhookok eltérnek az Automatizáláson belüli „Webhook küldése” lépéstől. A fiókszintű webhookok a Maildroppa kiválasztott fiókszintű eseményeire figyelnek. Az automatizálási webhook csak akkor kerül elküldésre, amikor egy feliratkozó eléri az adott lépést. Mindkettő a fiók webhook-aláírási titkát használja, ezért a titok cseréje minden olyan kimenő webhook-fogadót érint, amely ellenőrzi a Maildroppa-aláírásokat.

A Webhooks oldal megnyitása

Nyissa meg a „Beállítások” menüt, bontsa ki a „Fejlesztők” részt, majd válassza a „Webhooks” lehetőséget.

Az oldal három fő területet tartalmaz:

• Aláírási titok
• Végpontok
• A kiválasztott végpont kézbesítési előzményei

Ha egynél több végponttal rendelkezik, válasszon ki egy végpontsort a kézbesítési előzmények megjelenítéséhez. Ha nem választott ki végpontot, a Maildroppa a lista első végpontjának előzményeit jeleníti meg.

Végpont létrehozása előtt

A Maildroppa beállítása előtt készítsen elő egy fogadót a szerverén. A fogadónak:

• Nyilvános HTTPS-URL-en keresztül elérhetőnek kell lennie.
• application/json törzsű POST kéréseket kell fogadnia.
• A nyers kérés törzsét meg kell őriznie a Maildroppa-aláírás ellenőrzéséig.
• Csak akkor kell 2xx állapotkódot visszaadnia, amikor az eseményt biztonságosan elfogadta.
• Az ismételt kézbesítéseket az Eseményazonosító használatával idempotensen kell feldolgoznia.
• Gyorsan kell válaszolnia, és nem szabad lassú műveleteket végeznie a kérés alatt.

Megbízható megoldás az, ha ellenőrzi a kérést, tartós várólistába vagy adatbázisba menti az Eseményazonosítót és a hasznos adatokat, 200 vagy 204 választ ad vissza, majd később dolgozza fel az üzleti műveletet.

Éles webhookfogadóként ne tegyen közzé fejlesztői számítógépet, helyi hálózati címet vagy védelem nélküli szkriptet. A Maildroppa csak nyilvános HTTPS-célokat fogad el, és a kézbesítés elküldésekor ismét ellenőrzi a célhelyet.

1. lépés: Az aláírási titok létrehozása

---

Minden Maildroppa webhookkérés alá van írva. A fogadó az aláírási titok segítségével ellenőrzi, hogy a kérést a Maildroppa hozta-e létre, és hogy a törzs nem változott-e meg az átvitel során.

Az oldal tetején az Aláírási titok panel az alábbi állapotok egyikét jeleníti meg:

• Hiányzik — Még nincs aláírási titok.
• Kész — Be van állítva egy aláírási titok.
• Betöltés — A Maildroppa lekéri az aktuális állapotot.

Ha az állapot Hiányzik, kattintson a „Titok létrehozása” gombra.

A Maildroppa azonnal megjeleníti az új titkot. A titok whsec_ előtaggal kezdődik. Kattintson a „Másolás” gombra, majd tárolja a fogadó által használt titokkezelőben vagy védett környezeti konfigurációban.

A teljes érték csak közvetlenül a létrehozás vagy a csere után látható. Az oldal újratöltése vagy elhagyása után a Maildroppa csak azt jelzi, hogy létezik titok, és mikor frissítették utoljára. A tárolt titkot később nem fedi fel újra.

Ha elveszíti a titkot

Ha a fogadó már nem rendelkezik az aktuális titokkal, kattintson a „Titok cseréje” gombra, és mentse el az újonnan megjelenő értéket.

A csere azonnal lecseréli az előző titkot. A Maildroppa nem őrzi meg mindkét értéket átmeneti időszakra. Frissítsen minden fogadót, amely ezt a fióktitkot használja, mielőtt újabb teszteket küldene vagy az éles kézbesítésekre támaszkodna.

Az új kézbesítések, az ütemezett újrapróbálkozások, a tesztek és az újrajátszások az HTTP-kérés időpontjában aktuális titokkal vannak aláírva. Ez azt jelenti, hogy egy csere előtt létrehozott kézbesítés az új titokkal is aláírható, ha később próbálják meg elküldeni.

Kezelje a titkot jelszóként

Ne helyezze az aláírási titkot böngészőkódba, nyilvános tárolóba, URL-be, hibaoldalra vagy szokásos alkalmazásnaplóba.

Csak a szerveroldali fogadónak van szüksége a titokra. Ha úgy gondolja, hogy illetéktelenek hozzáférhettek, azonnal cserélje le, és frissítsen minden fogadót.

Webhook-aláírás ellenőrzése

Minden kérés az alábbi Maildroppa-fejléceket tartalmazza:

• X-Maildroppa-Event-Id — Az üzleti eseményt azonosítja.
• X-Maildroppa-Delivery-Id — Az adott kézbesítést azonosítja.
• X-Maildroppa-Timestamp — Az aláírás időpontja Unix-másodpercben.
• X-Maildroppa-Signature — A verziózott HMAC-aláírás.

A Maildroppa ezeket is elküldi:

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

Az aláírás formátuma:

v1=<lowercase hexadecimal HMAC>

A Maildroppa HMAC-SHA256 használatával hozza létre. Az aláírt tartalom az időbélyeg, amelyet egy pont követ, majd a pontos nyers JSON-kérés törzse:

<timestamp>.<raw request body>

HMAC-kulcsként használja az aláírási titkot.

Az alábbi Node.js-példa az alapvető ellenőrzési lépést mutatja be. A rawBody az eredeti kérés bájtjait kell hogy tartalmazza, nem pedig már feldolgozott, majd újra szerializált JSON-t.

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

Az aláírás ellenőrzése után hasonlítsa össze az időbélyeget a szerver idejével is. Utasítsa el az infrastruktúrájához választott rövid tolerancián kívüli kéréseket, például az öt percnél régebbieket. Ez csökkenti annak kockázatát, hogy egy elfogott, érvényes kérést jóval később újrajátszanak.

A JSON-t csak akkor elemezze és dolgozza fel, ha mindkét ellenőrzés sikeres volt.

Az aláírási hibák gyakori okai

Az aláírás általában az alábbi okok valamelyike miatt hibás:

• A fogadó csere után régi titkot használ.
• A köztes szoftver feldolgozta vagy módosította a JSON-t az aláírás kiszámítása előtt.
• A fogadó csak a törzset írja alá, és kihagyja a <timestamp>. részt.
• Az időbélyeget formázott dátumként kezeli a pontos fejlécérték helyett.
• Az összehasonlításból kimarad a v1= előtag.
• A kiszámított HMAC kódolása eltérő, nem pedig kisbetűs hexadecimális.

Sikertelen ellenőrzés esetén naplózza az Eseményazonosítót és a Kézbesítésazonosítót, de soha ne naplózza az aláírási titkot vagy az érzékeny egyéni fejlécértékeket.

2. lépés: Végpont hozzáadása

---

Kattintson a „Végpont hozzáadása” gombra a Végpontok szakaszban.

A szerkesztő négy részből áll:

• Végpont URL-je
• Események
• Egyéni fejlécek
• Aktív állapot

Az új végpontok aktívként jönnek létre, és a szerkesztőben kezdetben minden megjelenített esemény ki van választva. Mentés előtt ellenőrizze a kiválasztást, hogy a fogadó csak a ténylegesen szükséges értesítéseket kapja.

A végpont URL-jének beállítása

Adja meg a Maildroppa-kéréseket fogadó teljes nyilvános URL-t, például:

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

Az URL-nek meg kell felelnie az alábbi követelményeknek:

• https:// protokollt kell használnia.
• Érvényes nyilvános hosztnevet kell tartalmaznia.
• Legfeljebb 2048 karakter hosszú lehet.
• Nem tartalmazhat { vagy } jelet tartalmazó sablonváltozókat.
• Nem tartalmazhat felhasználónevet vagy jelszót a hosztnév előtt.
• Nem tartalmazhat # jellel kezdődő URL-töredéket.
• A szabványos 443-as HTTPS-portot kell használnia.
• Nem használhat localhost címet, nyers IP-címet, illetve olyan hosztnevet, amely tiltott privát vagy fenntartott hálózatra oldódik fel.

A lekérdezési paraméterek támogatottak, de ne helyezzen API-kulcsokat vagy más titkokat az URL-be. Az URL-ek láthatók a végpontlistában és a kézbesítési adatokban. A hitelesítő adatokhoz inkább egyéni fejlécet használjon.

A Maildroppa nem követi az átirányításokat. A végleges HTTPS-célt mentse el, ne olyan URL-t, amely 301, 302, 307 vagy 308 választ ad.

A küldés előtt a célhosztnév feloldása ismét megtörténik. A később privát vagy tiltott címre feloldódó hosztnevet a rendszer elutasítja, még akkor is, ha a végpont mentésekor érvényes volt.

Események kiválasztása

Válasszon ki legalább egy eseményt. A végpont csak a szerkesztőjében kiválasztott eseménytípusokat kapja meg.

Az oldal az alábbi eseményeket kínálja:

Feliratkozó létrehozva — subscriber.created

Akkor küldi a rendszer, amikor létrejön egy feliratkozó a Maildroppa-fiókban.

Ezzel az eseménnyel létrehozhatja a megfelelő kontaktot CRM-ben, ügyféladat-platformon, belső adatbázisban vagy más, engedélyeket figyelembe vevő rendszerben.

Ne értelmezze ezt az eseményt annak bizonyítékaként, hogy minden feliratkozás befejezte a Double Opt-in folyamatot. A hasznos adatokban szereplő feliratkozói állapot az aktuális állapotot írja le.

Feliratkozó frissítve — subscriber.updated

Akkor küldi a rendszer, amikor a beépített feliratkozói adatok vagy az egyéni mezők értékei megváltoznak.

A hasznos adatokban található teljes feliratkozói objektumot tekintse a Maildroppa aktuális reprezentációjának. Ne feltételezze, hogy csak egy adott tulajdonság módosult.

A címkék hozzárendelése és eltávolítása saját eseménytípussal rendelkezik, így külön kezelhetők.

Feliratkozó leiratkozott — subscriber.unsubscribed

Akkor küldi a rendszer, amikor a feliratkozó leiratkozási művelet következtében leiratkozott állapotba kerül.

Ezzel az eseménnyel tiltsa le a kontaktot a kapcsolódó rendszerekben. Ne iratkoztassa vissza automatikusan a személyt csak azért, mert egy másik rendszer még aktívként jelöli.

Címke hozzáadva — subscriber.tag_added

Akkor küldi a rendszer, amikor egy címkét hozzárendelnek egy feliratkozóhoz.

A hasznos adatok tartalmazzák az adott változásban érintett feliratkozót és címkét.

Címke eltávolítva — subscriber.tag_removed

Akkor küldi a rendszer, amikor egy címkét eltávolítanak egy feliratkozóról.

A hasznos adatok tartalmazzák a frissített feliratkozót és az eltávolított címkét. Az eltávolított címke külön is meg van adva, annak ellenére, hogy már nem szerepel a feliratkozó aktuális tags tömbjében.

Űrlap elküldve — form.submitted

Akkor küldi a rendszer, amikor egy látogató elküld egy Maildroppa-feliratkozási űrlapot.

Ezt űrlapbeküldési jelzésként kezelje, ne annak megerősítéseként, hogy a Double Opt-in folyamat befejeződött. Minden olyan munkafolyamatnak, amely megerősített feliratkozást igényel, továbbra is figyelembe kell vennie a feliratkozó aktuális állapotát és a megerősítési folyamatot.

Használjon külön végpontokat eltérő feladatokhoz

Különböző eseményeket különböző rendszerekbe küldhet. Például:

• A feliratkozói és címkeeseményeket küldje CRM-be.
• A leiratkozási eseményeket küldje elnyomási szolgáltatásba.
• Az űrlapbeküldési eseményeket küldje analitikai folyamatba.

A külön végpontok csökkentik a szükségtelen forgalmat, és megkönnyítik a hibák diagnosztizálását. Minden végpontnak saját eseménykiválasztása, URL-je, egyéni fejlécei, aktív állapota, tesztjei és kézbesítési előzményei vannak.

Egyéni fejlécek hozzáadása

Az egyéni fejlécek használata nem kötelező. Akkor használja őket, ha a fogadó API-kulcsot, bearer tokent, bérlőazonosítót vagy más rögzített fejlécet igényel.

Kattintson a „Fejléc hozzáadása” gombra, majd adja meg a fejléc nevét és értékét. Megfelelő példák:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Legfeljebb 20 egyéni fejlécet adhat hozzá.

A fejlécnevek:

• Kötelezők.
• Legfeljebb 128 karaktert tartalmazhatnak.
• Érvényes HTTP-fejlécnév-karaktereket kell használniuk.
• Kis- és nagybetűtől függetlenül egyedieknek kell lenniük.

A fejlécértékek:

• Kötelezők.
• Legfeljebb 2000 karaktert tartalmazhatnak.
• Nem tartalmazhatnak sortörést.

Az alábbi nevek foglaltak, ezért nem helyettesíthetők egyéni fejléccel:

• Content-Type
• Content-Length
• Host
• User-Agent
• Minden X-Maildroppa- kezdetű név

Ez megakadályozza, hogy egy egyéni érték felülírja a Maildroppa kézbesítési és aláírási fejléceit.

A fejlécben tárolt titkok kezelése

A Maildroppa titkosítja az egyéni fejlécértékeket, mielőtt tárolná őket. A mentett értékeket a böngésző nem kapja vissza olvasható formában.

A végpont későbbi szerkesztésekor az értékmezőben a „Tárolt érték megőrzése” szöveg jelenik meg. Hagyja üresen, ha a meglévő titoknak változatlanul kell maradnia. Adjon meg új értéket a cseréjéhez.

Ha módosítja a fejléc nevét, adja meg újra az értéket. A Maildroppa csak addig őrzi meg a tárolt titkot, amíg az eredeti fejlécnév változatlan marad.

Egy fejlécsor eltávolítása az adott fejlécet a végpont mentése után a jövőbeli kézbesítésekből is eltávolítja.

Az egyéni fejlécértékek érzékeny adatnak minősülnek a tárolt kérésinformációkban. A kézbesítési előzményekben maszkolva jelennek meg.

A végpont aktív vagy inaktív állapotának beállítása

Hagyja bejelölve az „Aktív” lehetőséget, ha a végpontnak azonnal fogadnia kell az eseményeket.

Törölje a jelölést, ha a konfigurációt úgy szeretné menteni, hogy még ne induljanak el kézbesítések. A végpontot később aktiválhatja a végpontlistából.

Egy inaktív végpont:

• Nem kapja meg az újonnan bekövetkező eseményeket.
• Nem küldhet teszt-webhookot.
• Látható és szerkeszthető marad.
• Megőrzi a meglévő kézbesítési előzményeket.

A végpont aktiválása nem pótolja azokat az eseményeket, amelyek inaktív állapotban történtek.

Kattintson a „Mentés” gombra, amikor az URL, az eseménykiválasztás, a fejlécek és az állapot megfelelő.

A végpontlista értelmezése

Minden végpontsor megjeleníti:

• A cél-URL-t.
• Egy Aktív vagy Inaktív jelvényt.
• A feliratkozott eseménytípusokat.
• Az egyéni fejlécek számát.
• A végpont utolsó frissítésének időpontját.

Az elérhető műveletek:

• Be/Ki — Aktiválja vagy deaktiválja a végpontot.
• Teszt — Egy azonnali tesztkérést küld egy aktív végpontra.
• Szerkesztés — Módosítja az URL-t, az eseményeket, a fejléceket vagy az aktív állapotot.
• Törlés — Megerősítés után véglegesen eltávolítja a végpontkonfigurációt.

Válassza ki egy sor fő részét az adott végpont kézbesítési előzményeinek megnyitásához a lista alatt.

A mentett módosítások hatása a meglévő kézbesítésekre

Egy fiókszintű esemény olyan kézbesítést hoz létre, amely az akkori végpont-URL, hasznos adatok és egyéni fejlécek pillanatfelvételét tartalmazza.

Az URL vagy az egyéni fejlécek szerkesztése az újonnan létrehozott kézbesítésekre van hatással. A már várólistára helyezett kézbesítés megőrzi eredeti célját és mentett fejléc-konfigurációját.

A kiválasztott események módosítása szintén csak az ezt követően bekövetkező eseményekre vonatkozik. A Maildroppa nem hoz létre visszamenőleg kézbesítéseket olyan eseménytípusokhoz, amelyek nem voltak kiválasztva az esemény bekövetkezésekor.

Az aláírási titok ettől eltér: a rendszer az HTTP-kérés előkészítésekor olvassa be. Ezért egy függőben lévő kézbesítés vagy újrajátszás újonnan cserélt aláírási titkot használhat akkor is, ha a hasznos adatai és a végpont pillanatfelvétele korábban jött létre.

Végpont tesztelése

Kattintson a „Teszt” gombra egy aktív végponton, miután a fogadó és az aláírási titok készen áll.

A Maildroppa azonnal elküld egy aláírt kérést a mentett végpont-URL és a mentett egyéni fejlécek használatával. A nyitott szerkesztő nem mentett módosításai nem részei a tesztnek.

A teszt hasznos adatai a webhook.test eseménytípust használják, és a livemode értéke 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."
  }
}

A létrehozott azonosítók és az időbélyeg minden valódi tesztnél eltérő.

A teszt pontosan egy HTTP-kísérletet hajt végre. A tesztkézbesítések nem kerülnek az éles újrapróbálkozási ütemezésbe, és nem játszhatók újra.

A kérés befejezése után az eredménypanel megjeleníti:

• Teszt sikeres vagy Teszt sikertelen
• Eseményazonosító
• HTTP-állapot, ha érkezett válasz
• Időtartam
• Kézbesítésazonosító
• Hibaadatok, ha elérhetők
• Válaszkivonat, ha a fogadó törzset küldött vissza

A teszt a Kézbesítési előzményekben is megjelenik Teszt jelvénnyel. A „Teszt” szűrővel csak a tesztkéréseket jelenítheti meg.

Az éles hasznos adatok értelmezése

Az éles fiókszintű események közös JSON-burkot használnak:

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

A legfelső szintű tulajdonságok jelentése:

• id — Az Eseményazonosító. Megegyezik az X-Maildroppa-Event-Id értékével.
• type — A végpont szerkesztőjében kiválasztott eseménykulcs.
• schema_version — A hasznos adatok sémaverziója. Használja az esemény feldolgozási módjának meghatározásához.
• created_at — A hasznos adatok létrehozásának időpontja UTC-ben.
• livemode — Éles eseményeknél true, teszteseményeknél false.
• data — Az eseményspecifikus tartalom.

Az eseményeket a pontos type érték alapján irányítsa. Hagyja figyelmen kívül azokat a további tulajdonságokat, amelyekre az integrációjának nincs szüksége, hogy a kompatibilis bővítések ne okozzák a fogadó hibáját.

Feliratkozói események hasznos adatai

A feliratkozói események az aktuális feliratkozói reprezentációt a data.subscriber alatt tartalmazzák:

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

A fields és a tags tömb. Üresek is lehetnek. Egy feliratkozói tulajdonság akkor is lehet null, ha nincs értéke, ezért a fogadónak a hasznosadat-sémát kell követnie, nem pedig feltételeznie, hogy minden opcionális profilérték jelen van.

Címkeesemények hasznos adatai

A címkeesemények tartalmazzák a feliratkozót és az eseményt kiváltó címkét is:

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

A subscriber.tag_removed esetén a data.tag továbbra is az eltávolított címkét azonosítja, annak ellenére, hogy a feliratkozó aktuális tags tömbje már nem tartalmazza.

Eseményazonosítók, kézbesítésazonosítók és idempotencia

Az Eseményazonosító és a Kézbesítésazonosító eltérő célokat szolgál.

Eseményazonosító

Az Eseményazonosító az üzleti eseményt azonosítja. A következő helyeken jelenik meg:

• A hasznos adatok legfelső szintű id tulajdonságában.
• Az X-Maildroppa-Event-Id kérésfejlécben.
• A kézbesítési előzményekben.

Ugyanazt az eseményt több feliratkozott végpont is megkaphatja. Ezek a kézbesítések ugyanazzal az Eseményazonosítóval rendelkeznek.

Az újrapróbálkozások és a kézi újrajátszások is megőrzik az eredeti Eseményazonosítót. Tárolja a feldolgozott Eseményazonosítókat, és tegye idempotenssé az üzleti műveletet, hogy egy ismételt kérés ne hozzon létre ismétlődő kontaktot, ne ismételjen meg visszafordíthatatlan műveletet, és ne alkalmazza kétszer ugyanazt a módosítást.

Kézbesítésazonosító

A Kézbesítésazonosító egy kézbesítési rekordot azonosít. A következő helyeken jelenik meg:

• Az X-Maildroppa-Delivery-Id kérésfejlécben.
• A kézbesítési előzményekben.

Minden végpontkézbesítés saját Kézbesítésazonosítóval rendelkezik. A kézi újrajátszás új Kézbesítésazonosítót hoz létre, miközben megőrzi az eredeti Eseményazonosítót.

A Kézbesítésazonosítót technikai nyomon követéshez és támogatáshoz használja. Üzleti szintű duplikációk kiszűréséhez az Eseményazonosítót használja.

A megfelelő HTTP-válasz visszaadása

A Maildroppa a válaszokat a következőképpen osztályozza:

• Bármely 2xx válasz sikeresnek jelöli a kézbesítést.
• A 408 Request Timeout, 429 Too Many Requests és 5xx válaszok átmeneti hibák, amelyeknél újrapróbálkozás történhet.
• Az átmenetinek tekinthető hálózati hibáknál újrapróbálkozás történik.
• Az átirányításokat és az egyéb 3xx válaszokat a rendszer nem követi, hanem végleges hibaként kezeli.
• Az egyéb 4xx válaszokat végleges hibaként kezeli, és nem próbálja újra.

Csak akkor adjon vissza 200, 202 vagy 204 választ, amikor az eseményt biztonságosan elfogadta. Ha a feldolgozás időt vesz igénybe, először mentse el az eseményt, adjon vissza sikeres választ, majd aszinkron módon végezze el a lassabb munkát.

Ne adjon vissza átirányítást egy másik webhook-URL-re. Ehelyett állítsa be a végleges URL-t a Maildroppában.

Automatikus újrapróbálkozási ütemezés

Az éles kézbesítések legfeljebb hét HTTP-kísérletet tehetnek.

Újrapróbálható hiba után a Maildroppa az alábbi késleltetésekkel ütemezi a következő kísérletet:

1. Az 1. kísérlet után: 1 perc
2. A 2. kísérlet után: 5 perc
3. A 3. kísérlet után: 30 perc
4. A 4. kísérlet után: 2 óra
5. Az 5. kísérlet után: 12 óra
6. A 6. kísérlet után: 24 óra

Ha a 7. kísérlet továbbra is újrapróbálható hibát kap, a kézbesítés Halott állapotba kerül, és a rendszer nem ütemez további automatikus kísérletet.

Az ütemezés az egyes sikertelen kísérletektől számítandó. A tényleges kézbesítés kissé később történhet, mivel a kézbesítések aszinkron módon zajlanak, és rendszerbiztonsági korlátok is vonatkoznak rájuk.

Lehetőség szerint még a megjelenített „Következő újrapróbálkozás” időpontja előtt javítsa ki az átmeneti fogadóhibát. Ha az automatikus kísérletek véget értek, használja az Újrajátszás lehetőséget, miután a fogadó ismét működőképes.

A kézbesítési előzmények értelmezése

A kézbesítési előzmények az aktuálisan kiválasztott végponthoz tartoznak. A végpont URL-je megjelenik a szakasz fejlécében, így ellenőrizheti, mely előzményeket tekinti meg.

Használja az alábbi szűrőket:

• Összes — Éles és tesztkézbesítéseket is megjelenít.
• Éles — Csak éles események kézbesítéseit jeleníti meg.
• Teszt — Csak a kézi teszteket jeleníti meg.

A legfrissebb állapot lekéréséhez kattintson a „Frissítés” gombra. Nem szükséges nyitva hagynia az előzményeket, miközben a Maildroppa kézbesítést küld vagy próbál újra.

Az oldal a kiválasztott szűrő legfeljebb 50 legfrissebb egyező kézbesítését jeleníti meg.

Kézbesítési oszlopok

Minden sor tartalmazza:

• Létrehozva — A kézbesítési rekord létrehozásának időpontja.
• Állapot — Függőben, Sikeres, Sikertelen vagy Halott.
• HTTP — Válaszállapot, kísérletszám, időtartam és adott esetben a következő újrapróbálkozás időpontja.
• Feliratkozó — A feliratkozó e-mail-címe, ha az esemény feliratkozóhoz kapcsolódik.
• Kézbesítés — Eseménytípus, Eseményazonosító és Kézbesítésazonosító.
• Műveletek — Újrajátszás, ha a kézbesítés jogosult rá.

Ha nem történt HTTP-kérés, a HTTP oszlopban a „Nem történt HTTP-kísérlet” szöveg jelenik meg. Ez akkor fordulhat elő, amikor a Maildroppa küldés előtt elutasítja a kérést, például mert hiányzik az aláírási titok, vagy a mentett célhely már nem használható biztonságosan.

Ha elérhető, a sor a fogadó által visszaadott hibát és válaszkivonatot is megjeleníti. Ne adjon vissza titkokat vagy érzékeny személyes adatokat a webhook válaszának törzsében, mert a válasz egy része megjelenhet a fiók kézbesítési naplójában.

Kézbesítési állapotok

A Függőben azt jelenti, hogy a kézbesítés az első kísérletre vagy egy ütemezett újrapróbálkozásra vár. A „Következő újrapróbálkozás” akkor jelenik meg, ha újabb kísérletet ütemeztek.

A Sikeres azt jelenti, hogy a fogadó 2xx választ adott. Nincs szükség további automatikus kísérletre.

A Sikertelen azt jelenti, hogy a kézbesítés nem újrapróbálható problémával zárult, a rendszer elutasította HTTP-kísérlet előtt, vagy leállították, mielőtt elküldhették volna.

A Halott azt jelenti, hogy egy újrapróbálható probléma esetén minden automatikus kísérletet felhasználtak anélkül, hogy sikeres válasz érkezett volna.

Előzmények megőrzése

A kézbesítési rekordokat korlátozott ideig őrzi meg a rendszer:

• Sikeres éles kézbesítések: 30 nap
• Sikertelen éles kézbesítések: 90 nap
• Halott éles kézbesítések: 90 nap
• Tesztkézbesítések: 30 nap

Ha hosszabb auditálási előzményekre van szüksége, vezessen saját integrációs naplókat. Tárolja az Eseményazonosítókat és Kézbesítésazonosítókat, de kerülje a titkok szükségtelen tárolását.

Kézbesítés újrajátszása

Kattintson az „Újrajátszás” gombra, ha egy befejezett éles kézbesítést újra meg kell próbálni.

Az újrajátszás a Sikeres, Sikertelen vagy Halott állapotú éles kézbesítéseknél érhető el. Függőben lévő kézbesítésnél nem érhető el, és a tesztkézbesítések nem játszhatók újra.

Az újrajátszás:

• Új, Függőben állapotú kézbesítést hoz létre.
• Új Kézbesítésazonosítót hoz létre.
• Megőrzi az eredeti Eseményazonosítót.
• Megőrzi az eredeti eseménytípust és JSON-hasznos adatokat.
• Az eredeti mentett cél-URL-t és egyéni fejléc-pillanatfelvételt használja.
• Az új kérés előkészítésekor aktuális aláírási titkot használja.

Az újrajátszás nem építi újra a hasznos adatokat a feliratkozó aktuális adataiból. Az eredeti esemény pillanatfelvételét küldi el újra. Ez auditálhatóvá teszi az újrajátszást, és megakadályozza, hogy egy korábbi esemény jelentése észrevétlenül megváltozzon.

Ugyanannak a forráskézbesítésnek egyszerre csak egy újrajátszása lehet Függőben. Várja meg, amíg az újrajátszás befejeződik, mielőtt újat kérne.

Az újrajátszás előtt győződjön meg róla, hogy a végpont Aktív. Ha a végpont inaktív, a várólistára helyezett újrajátszás nem kézbesíthető sikeresen.

Mivel a fogadó akkor is végrehajthatta az üzleti műveletet, ha a Maildroppa nem kapta meg a sikeres választ, az újrajátszás ismétlődő kérést eredményezhet. Az Eseményazonosító deduplikálása megvédi a kapcsolódó rendszert a művelet megismétlésétől.

Végpont szerkesztése

Kattintson a „Szerkesztés” gombra az URL, az eseménykiválasztás, az egyéni fejlécek vagy az aktív állapot módosításához.

Mentés előtt:

1. Ellenőrizze, hogy az új URL már elérhető.
2. Hagyja üresen a tárolt fejlécértékeket, ha változatlanul kell maradniuk.
3. Adjon meg új értéket minden átnevezett fejléchez.
4. Ellenőrizze az eseménykiválasztást, hogy ne távolítsa el véletlenül a szükséges értesítéseket.
5. Mentsen, és küldjön új teszt-webhookot.

Ne feledje, hogy a várólistán lévő kézbesítések megőrzik meglévő URL-jüket és egyéni fejléc-pillanatfelvételüket. Az új konfigurációt a jövőbeli kézbesítéseken tesztelje, ne feltételezze, hogy egy régebbi várólistás kérést is módosít.

Végpont deaktiválása

Használja a Be/Ki kapcsolót, ha egy integrációt a konfiguráció és az előzmények törlése nélkül szeretne szüneteltetni.

Amikor egy végpontot kikapcsol:

• Új események nem kerülnek többé várólistára hozzá.
• A küldéshez még nem lefoglalt, függőben lévő kézbesítések Sikertelen állapotúvá válnak.
• A Teszt lehetőség letiltódik.
• A végpont továbbra is szerkeszthető és később aktiválható marad.

A deaktiválás pillanatában már folyamatban lévő kérés még befejeződhet. A végpont kikapcsolása után tekintse meg a Kézbesítési előzményeket, ha ez a különbség fontos az integrációja szempontjából.

A végpont inaktív állapotában kimaradt eseményeket a későbbi újbóli bekapcsolás nem pótolja.

Végpont törlése

Kattintson a „Törlés” gombra, majd erősítse meg a figyelmeztetést, ha a végpontra már nincs szükség.

A törlés eltávolítja a végpontot az oldalról, leállítja a jövőbeli eseménykézbesítéseket, és Sikertelen állapotúvá teszi azokat a függőben lévő kézbesítéseket, amelyeket még nem foglaltak le küldésre.

A törlés nem ideiglenes szüneteltetésre szolgál. Használja a Be/Ki kapcsolót, ha később szüksége lehet a konfigurációra vagy annak látható előzményeire.

Törlés előtt jegyezze fel az integráció auditjához még szükséges Eseményazonosítókat vagy Kézbesítésazonosítókat.

Hibaelhárítás

A végpont nem menthető

Ellenőrizze, hogy:

• Az URL https:// előtaggal kezdődik.
• Az URL nyilvános hosztnevet és a 443-as portot használja.
• Az URL nem tartalmaz változókat, bejelentkezési adatokat vagy töredéket.
• Legalább egy esemény ki van választva.
• Minden egyéni fejléchez egyedi név és érték tartozik.
• Nem használja a fenntartott Maildroppa- és HTTP-fejlécneveket egyéni névként.

A Teszt le van tiltva

A Teszt csak aktív végpontnál érhető el. Kapcsolja be a végpontot, vagy szerkessze, és válassza az „Aktív” lehetőséget, majd mentés után teszteljen.

A teszt nem mutat HTTP-kísérletet

Hozzon létre aláírási titkot, ha az állapot Hiányzik. Ellenőrizze azt is, hogy a célhosztnév nyilvános-e, és továbbra is megfelelően oldódik-e fel.

A rendszer még küldés előtt elutasíthatja a kérést, ha a titok, az URL, az egyéni fejlécek vagy a célhely biztonsági ellenőrzése érvénytelen.

A fogadó 401 vagy 403 választ ad

Ellenőrizze a mentett egyéni fejléc nevét és a hitelesítő adatot. Szerkessze a végpontot, és adja meg újra az értéket, ha megváltozott.

Győződjön meg arról is, hogy a fogadó nem keveri össze a saját API-hitelesítő adatát a Maildroppa-aláírással. Az egyéni engedélyezési fejléc és az X-Maildroppa-Signature eltérő célokat szolgál, és egymástól függetlenül ellenőrizhetők.

A fogadó átirányítást ad vissza

A Maildroppa nem követi az átirányításokat. Cserélje le a végpont URL-jét a végleges nyilvános HTTPS-URL-re, majd teszteljen újra.

Az aláírás nem egyezik

Ellenőrizze, hogy a fogadó:

• Az aktuális aláírási titkot használja.
• A pontos X-Maildroppa-Timestamp értéket használja.
• A <timestamp>.<raw request body> értéket írja alá.
• HMAC-SHA256-ot és kisbetűs hexadecimális kimenetet használ.
• A teljes értéket, a v1= előtaggal együtt hasonlítja össze.
• Az összehasonlítást még azelőtt végzi el, hogy a JSON-feldolgozás módosítaná a törzset.

Ugyanaz az esemény többször érkezik meg

Ez hálózati megszakítás, újrapróbálkozás vagy kézi újrajátszás után fordulhat elő. A webhookkézbesítési rendszereknél normális, hogy legalább egyszeri kézbesítést biztosítanak, nem pedig pontosan egyszerit.

Használja az Eseményazonosítót idempotenciakulcsként. Adjon vissza 2xx választ, ha egy már feldolgozott Eseményazonosító ismét beérkezik, és nincs szükség további műveletre.

Egy kézbesítés függőben van

Tekintse meg a HTTP oszlopban a „Következő újrapróbálkozás” értékét. Az újrapróbálható 408, 429, 5xx vagy átmeneti hálózati hiba esetén a kézbesítés a következő ütemezett kísérletig Függőben marad.

Az újrapróbálkozás időpontja után kattintson a „Frissítés” gombra a legfrissebb állapot betöltéséhez.

Egy kézbesítés Halott állapotú

Minden automatikus kísérletet felhasználtak. Először javítsa ki a fogadót, győződjön meg arról, hogy a végpont Aktív, küldjön teszt-webhookot, majd használja az Újrajátszás lehetőséget az éles kézbesítésnél.

Ajánlott éles használati ellenőrzőlista

Mielőtt egy végpontra éles környezetben támaszkodna, ellenőrizze az alábbiakat:

1. A fogadó stabil, nyilvános HTTPS-URL-t és érvényes tanúsítványt használ.
2. Az aláírási titkot a forráskódon kívül tárolja.
3. Az aláírást a módosítatlan nyers törzs alapján ellenőrzi.
4. A régi időbélyegeket dokumentált tolerancia alapján elutasítja.
5. A fogadó tárolja és deduplikálja az Eseményazonosítókat.
6. A fogadó naplózza az Eseményazonosítókat és Kézbesítésazonosítókat a nyomon követéshez.
7. A lassú feldolgozás csak az esemény tartós elfogadása után történik.
8. Csak elfogadott események esetén ad vissza 2xx választ.
9. Az egyéni hitelesítő adatokat fejlécekben, nem pedig az URL-ben tárolja.
10. Csak a szükséges eseménytípusokat választja ki.
11. A teszt-webhook sikeres, és megfelelően megjelenik a Kézbesítési előzményekben.
12. A figyelés értesíti, amikor az éles kézbesítések hibákat kezdenek visszaadni.

Ezekkel a védelmi intézkedésekkel a Webhooks oldal egy megbízható integráció mindkét oldalát biztosítja: biztonságos eseménykézbesítést az alkalmazásának és átlátható működési előzményeket a Maildroppán belül.