Tudásbázis

Webhookok

Szólunk a végpontodnak, amikor levél érkezik, ahelyett hogy neked kellene lekérdezned.

Részletek

Ma is használható a Beállítások → Webhookok alól és az API-n keresztül: regisztrálj egy https végpontot, válaszd ki, melyiket kéri a húsz esemény közül, és másold ki a whsec_ aláíró titkot, amelyet létrehozáskor és forgatáskor mutatunk meg, többé soha. A kézbesítések valódi, aláírt POST kérések, amelyeket maga a postafiók vált ki, nem pedig valamelyik API-hívás, így bejövő levélnél, valamint megnyitásnál és kattintásnál is elsülnek, bármi küldte is az üzenetet. A küldés minden felületről elsül, korábban viszont csak némelyikről: az API-n, az MCP-n, egy sablonon vagy egy szabályon keresztüli küldés email.sent eseményt váltott ki, míg az alkalmazás saját szerkesztőjéből küldött üzenet nem, mert a szerkesztő közvetlenül a postafiókba ír, nem azon a küldési szolgáltatáson keresztül, amely az eseményt kibocsátotta. Az eseményt most már magánál a postafióknál váltjuk ki, ahol mindegyik találkozik, így az alkalmazásban való megírás, a keddre időzítés és az API-ra küldés három módja ugyanannak a webhooknak a kiváltására. A halasztott küldés kétszer is jelez: email.scheduled vagy email.queued, amikor elfogadjuk, email.sent, amikor ténylegesen elmegy, és email.cancelled, ha közben visszaveszed. Postafiókonként tíz végpont, mindenhol érvényesítve, ahol végpontot regisztrálnak, nem csak ezen a képernyőn.
Az események három családba tartoznak. Tizenöt egyetlen üzenetről szól: email.received, email.replied, email.sent, email.delivered, email.failed, email.cancelled, email.scheduled, email.queued (a scheduled visszavonható küldéses testvére), email.delivery_delayed, email.bounced, email.complained, email.suppressed, email.opened, email.clicked és email.downloaded. Az email.sent azt jelenti, hogy a küldő szolgáltatás elfogadta az üzenetet, az email.delivered azt, hogy a fogadó szerver, az email.delivery_delayed pedig azt, hogy még nem érkezett meg, és továbbra is újrapróbálkozunk vele. Az email.replied az email.received mellett sül el, amikor az érkező üzenet egy már a postafiókban lévőre válaszol, így az a fogyasztó, amelyik mindkettőt kéri, mindkettőt megkapja. Az email.downloaded akkor sül el, amikor valaki letölt egy fájlt, amely letöltési hivatkozásként ment ki – ugyanaz az osztályozó tartja ki a számlálásból a szkennereket és a hivatkozás-előnézőket –, és nem nevez meg címzettet, mert a hivatkozás mindenki számára ugyanaz, akinek az üzenet ment. Három egy domainről szól: domain.verified, amikor fogadni kezd, domain.sending_changed, amikor a küldési ítélete megváltozik, és domain.deleted, amikor eltávolítják, akár te kérted, akár a hétnapos takarító ejtette ellenőrizetlenül. Kettő magáról a letiltási listáról szól, ami más, mint az email.suppressed: suppression.added, amikor egy cím felkerül rá, suppression.removed, amikor egy címet újra engedélyezünk. Ha egyikre sem iratkozol fel, az minden üzeneteseményt jelent az email.replied kivételével – ma tizennégyet –, sosem a később hozzáadott családokat, és az API ezt ["*"] formában adja vissza. Nevezd meg a kívánt eseményeket, ha inkább kifejezett lennél. Minden kézbesítés visz egy X-OpenEmail-Signature fejlécet t=<unix>,v1=<hex> alakban, amely HMAC-SHA-256 az időbélyeg, egy pont és a nyers törzs felett, valamint egy X-OpenEmail-Event és egy X-OpenEmail-Delivery fejlécet. A bájtokat abban a formában ellenőrizd, ahogy megérkeztek: az értelmezés és újraszerializálás átrendezi a kulcsokat, és elrontja az aláírást. A 300 másodperces visszajátszási ablak érvényesítése a fogadó dolga, és az SDK ellenőrzője alapértelmezésben ezt használja.
A regisztrációt visszautasítjuk mindenre, ami nem https vagy nem nyilvánosan irányítható (loopback, RFC1918, link-local, CGNAT és az IPv6-os megfelelőik), az átirányításokat pedig nem követjük, így a 3xx válasz sikertelen kézbesítésként rögzül, nem pedig máshová követjük. A fogadó 5 másodpercet kap, a végpontokra párhuzamosan kézbesítünk, így tíz végpont is 5 másodpercbe kerül, nem 50-be, a legutóbbi próbálkozásokat pedig az adott végpont oldalán soroljuk fel a válaszkóddal és azzal, mennyi ideig tartott.
Egy kézbesítéssel legfeljebb ötször próbálkozunk. Az első az esemény pillanatában indul; azt a hibát, amely hihetően magától elmúlhat, 1 perc, majd 5, majd 25 perc, majd 2 óra múlva próbáljuk újra, ami egy eseményt körülbelül két és fél órára nyújt el. Az újrapróbálkozásokat tartós munkaként tartjuk nyilván, nem a memóriában, így az ablak közepén végzett üzembe helyezés nem veszíti el őket. Csak az ismétlésre érdemes hibákat ismételjük: időtúllépés, elutasított kapcsolat, 408, 425, 429 vagy bármilyen 5xx. Minden más 4xx azt jelenti, hogy a végpont szándékosan utasítja vissza a tartalmat, és négyszer újrakérdezni négyszeres terhelés lenne ugyanazért a válaszért. Az esemény azonosítóját egyszer hozzuk létre, és minden próbálkozás magával viszi az X-OpenEmail-Delivery fejlécben, így az a fogadó, amelyik kétszer látja ugyanazt az azonosítót, a másodikat eldobhatja, ahelyett hogy kétszer cselekedne. Ha 100 esemény egymás után minden próbálkozással elbukik, a végpontot letiltjuk, a munkaterületet e-mailben értesítjük, az ok pedig magán a végponton olvasható. A 410 Gone választ adó végpontot azonnal letiltjuk.
Azt a végpontot, amely 100-szor egymás után elbukik, inkább kikapcsoljuk, mintsem örökké tárcsázzuk, és erről mindenkit e-mailben értesítünk, akinek van webhookhozzáférése: melyikről van szó, mit jelentett az utolsó próbálkozás, és hogy semmi nem került sorba, amíg hibázott. A számláló EGYMÁST KÖVETŐ hibákat számol, és minden sikeres kézbesítés nullázza, így egy tavaly márciusi rossz délután nem adódhat össze egy ma letiltott végponttá. A visszakapcsolás egyúttal törli a számlálót is. A konzol megkülönbözteti a két állapotot, nem pedig egyetlen kapcsolót mutat: az általad kikapcsolt végpont másképp néz ki, mint az, amelyet mi kapcsoltunk ki.
A végpontok kezelése egy feladat két bejárattal. Az API-n ez a POST /webhooks, a patch, a delete, a rotate-secret, a test és a kézbesítési napló, az SDK-ban mindegyikhez egy-egy metódussal; az alkalmazásban pedig a Beállítások → Webhookok, ugyanazon nyilvántartás ellenében, nem egy másodikkal szemben. Az olvasás a webhooks:read hatókörhöz kötött, így bárki, aki integrációt épít, láthatja a végpontokat és a kézbesítési előzményeiket (melyik sült el, mit válaszolt a fogadó, mennyi ideig tartott) anélkül, hogy tulajdonos lenne. A regisztrálás, szerkesztés, tesztelés, forgatás és törlés webhooks:write hatókört ÉS a postafiók tulajdonlását igényli, mindkét felületen, és ez a második fele szándékos: a végpontnak nincs címtengelye, így a munkaterület összes címét megkapja, tárgyakkal és címzettekkel együtt, és a jogosultság hiánya azt jelenti, hogy „mindez elküldhető neki”. Az olyan szerepkör, amely integrációkat épít, de nem olvassa a leveleket, munkaterületi kulccsal vezérli ezt.