Base de coneixement

Webhooks

Avisen el vostre punt final quan arriba correu, en comptes d'obligar-vos a consultar-ho periòdicament.

Detalls

Utilitzables avui des de Configuració → Webhooks i per l'API: registreu un punt final https, trieu quins dels vint esdeveniments vol i copieu el secret de signatura whsec_, que es mostra en crear-lo i en rotar-lo, i mai més. Els lliuraments són POST signats de debò generats per la mateixa bústia i no pas per cap crida a l'API, així que es disparen amb el correu entrant i amb les obertures i els clics, sigui quin sigui el que ha enviat el missatge. L'enviament es dispara des de totes les superfícies, i abans només ho feia des d'algunes: un enviament per l'API, per MCP, per una plantilla o per una regla generava email.sent, mentre que un missatge enviat des del redactor de la mateixa aplicació no, perquè el redactor escriu directament a la bústia i no pas a través del servei d'enviament que emetia l'esdeveniment. Ara l'esdeveniment es genera a la bústia mateixa, que és on es troben tots, de manera que redactar a l'aplicació, programar per dimarts i publicar a l'API són tres maneres de provocar el mateix webhook. Un enviament diferit ho diu dues vegades: email.scheduled o email.queued quan s'accepta, email.sent quan surt de debò, i email.cancelled si el recupereu entremig. Deu punts finals per bústia, aplicat allà on se'n registri un i no només en aquesta pantalla.
Els esdeveniments vénen en tres famílies. Quinze tracten d'un missatge: email.received, email.replied, email.sent, email.delivered, email.failed, email.cancelled, email.scheduled, email.queued (el germà de scheduled per a desfés l'enviament), email.delivery_delayed, email.bounced, email.complained, email.suppressed, email.opened, email.clicked i email.downloaded. email.sent vol dir que el servei d'enviament ha acceptat el missatge, email.delivered vol dir que ho ha fet el servidor receptor, i email.delivery_delayed vol dir que encara no ha arribat i que s'hi continua reintentant. email.replied es dispara al costat de email.received quan el missatge que arriba respon a un que ja és a la bústia, de manera que un consumidor que vulgui tots dos els rep tots dos. email.downloaded es dispara quan una persona baixa un fitxer que va sortir com a enllaç de descàrrega, amb el mateix classificador que manté els escàners i els previsualitzadors d'enllaços fora del recompte, i no indica cap destinatari, perquè l'enllaç és el mateix per a tothom a qui va anar el missatge. Tres tracten d'un domini: domain.verified quan comença a rebre, domain.sending_changed quan canvia el seu veredicte d'enviament, i domain.deleted quan s'elimina, tant si ho heu demanat vosaltres com si el segador dels set dies l'ha descartat sense verificar. Dos tracten de la llista de supressió mateixa, que és una cosa diferent de email.suppressed: suppression.added quan una adreça hi entra, suppression.removed quan se'n torna a permetre una. No subscriure's a cap vol dir tots els esdeveniments de missatge excepte email.replied, catorze avui, mai una família afegida més endavant, i l'API ho retorna com a ["*"]. Indiqueu els esdeveniments que voleu si preferiu ser explícits. Cada lliurament porta X-OpenEmail-Signature en la forma t=<unix>,v1=<hex>, un HMAC-SHA-256 sobre la marca de temps, un punt i el cos en cru, a més de X-OpenEmail-Event i X-OpenEmail-Delivery. Verifiqueu-ho contra els bytes tal com han arribat: analitzar-los i tornar-los a serialitzar reordena les claus i trenca la signatura. La finestra de repetició de 300 segons l'ha d'aplicar el receptor, i el verificador de l'SDK la fa servir per defecte.
El registre es rebutja per a qualsevol cosa que no sigui https o que no sigui encaminable públicament (loopback, RFC1918, enllaç local, CGNAT i els equivalents en IPv6), i no se segueixen les redireccions, de manera que un 3xx es registra com a lliurament fallit en comptes de perseguir-lo a un altre lloc. El receptor disposa de 5 segons, els punts finals es lliuren en paral·lel, així que deu punts finals continuen costant 5 segons i no pas 50, i els intents recents s'enumeren a la pàgina d'aquell punt final amb el codi de resposta i el temps que ha trigat.
Un lliurament s'intenta fins a cinc vegades. El primer surt en el moment que passa l'esdeveniment; una fallada que plausiblement es podria resoldre sola es reintenta al cap d'1 minut, després 5, després 25 i després 2 hores, cosa que reparteix un mateix esdeveniment al llarg d'unes dues hores i mitja. Els reintents es guarden com a feina duradora i no pas en memòria, de manera que un desplegament enmig d'aquesta finestra no els perd. Només es repeteixen les fallades que val la pena repetir: un temps d'espera esgotat, una connexió rebutjada, 408, 425, 429 o qualsevol 5xx. Qualsevol altre 4xx és el punt final rebutjant la càrrega útil deliberadament, i demanar-ho quatre vegades més seria quatre vegades la càrrega per a la mateixa resposta. L'id de l'esdeveniment s'encunya un sol cop i cada intent el porta a X-OpenEmail-Delivery, de manera que un receptor que vegi el mateix id dues vegades pot descartar el segon en comptes d'actuar-hi dues vegades. Quan 100 esdeveniments seguits fallen tots els intents, el punt final es desactiva, s'envia un correu a l'espai de treball i el motiu es pot llegir al mateix punt final. Un punt final que respon 410 Gone es desactiva a l'instant.
Un punt final que falla 100 vegades seguides es desactiva en comptes de trucar-hi per sempre, i s'envia un correu a tothom que tingui accés als webhooks per dir-ho: quin és, què ha informat l'últim intent, i que no s'ha encuat res mentre fallava. El recompte és CONSECUTIU i qualsevol intent lliurat el reinicia, de manera que una mala tarda del març passat no pot sumar fins a desactivar un punt final avui. Tornar-lo a activar també esborra el recompte. La consola distingeix els dos estats en comptes de mostrar un sol commutador: un punt final que heu desactivat vosaltres es veu diferent d'un que hem desactivat nosaltres.
Gestionar punts finals és una sola feina amb dues portes d'entrada. Per l'API és POST /webhooks, el patch, el delete, rotate-secret, test i el registre de lliuraments, amb un mètode per a cadascun a l'SDK; a l'aplicació és Configuració → Webhooks, contra el mateix registre i no pas un de segon. La lectura està protegida per webhooks:read, de manera que qualsevol persona que construeixi una integració pot veure els punts finals i el seu historial de lliuraments (quin s'ha disparat, què ha respost el receptor, quant ha trigat) sense ser-ne la propietària. Registrar, editar, provar, rotar i suprimir requereixen webhooks:write I la propietat de la bústia, a totes dues superfícies, i aquesta segona meitat és deliberada: un punt final no té eix d'adreça, de manera que rep totes les adreces que té l'espai de treball amb els assumptes i els destinataris inclosos, i cap permís no vol dir «se li pot enviar tot això». Un rol que construeix integracions i no llegeix el correu ho condueix amb una clau d'espai de treball.