Zināšanu bāze

Webhooks

Paziņo jūsu galapunktam, kad pienāk pasts, nevis liek jums aptaujāt.

Detaļas

Lietojams jau šodien sadaļā Settings → Webhooks un caur API: reģistrējiet https galapunktu, izvēlieties, kurus no divdesmit notikumiem tas grib, un nokopējiet whsec_ parakstīšanas slepeno atslēgu, kas tiek parādīta izveidojot un rotējot, bet vairs nekad. Piegādes ir īsti parakstīti POST pieprasījumi, ko rada pati pastkaste, nevis kāds API izsaukums, tāpēc tie nostrādā gan ienākošam pastam, gan atvēršanām un klikšķiem neatkarīgi no tā, kas ziņu nosūtīja. Sūtīšana tagad nostrādā no katras virsmas, bet agrāk — tikai no dažām: sūtījums caur API, MCP, veidni vai noteikumu radīja email.sent, savukārt ziņa, kas nosūtīta no pašas lietotnes rakstīšanas loga, to nedarīja, jo rakstīšanas logs raksta tieši pastkastē, nevis caur sūtīšanas pakalpojumu, kas šo notikumu izstaroja. Tagad notikums tiek radīts pašā pastkastē, kur tie visi satiekas, tāpēc rakstīšana lietotnē, ieplānošana uz otrdienu un nosūtīšana caur API ir trīs veidi, kā izraisīt vienu un to pašu webhook. Atlikts sūtījums par sevi paziņo divreiz: email.scheduled vai email.queued, kad tas tiek pieņemts, email.sent, kad tas tiešām aiziet, un email.cancelled, ja pa vidu to atsaucat. Desmit galapunkti vienai pastkastei, un tas tiek ievērots visur, kur galapunktu reģistrē, nevis tikai šajā ekrānā.
Notikumi nāk trijās saimēs. Piecpadsmit ir par vienu ziņu: email.received, email.replied, email.sent, email.delivered, email.failed, email.cancelled, email.scheduled, email.queued (sūtīšanas atsaukšanas radinieks notikumam scheduled), email.delivery_delayed, email.bounced, email.complained, email.suppressed, email.opened, email.clicked un email.downloaded. email.sent nozīmē, ka ziņu pieņēma sūtīšanas pakalpojums, email.delivered nozīmē, ka to pieņēma saņemošais serveris, un email.delivery_delayed nozīmē, ka tā vēl nav pienākusi un mēģinājumi turpinās. email.replied nostrādā līdzās email.received, kad pienākošā ziņa atbild uz kādu, kas jau ir pastkastē, tāpēc patērētājs, kas grib abus, saņem abus. email.downloaded nostrādā, kad cilvēks lejupielādē failu, kas aizgāja kā lejupielādes saite; tas pats klasifikators neļauj skeneriem un saišu priekšskatītājiem iekļūt skaitā, un saņēmējs netiek nosaukts, jo saite ir vienāda visiem, kam ziņa aizgāja. Trīs ir par domēnu: domain.verified, kad tas sāk saņemt, domain.sending_changed, kad mainās tā sūtīšanas spriedums, un domain.deleted, kad tas tiek noņemts — vai nu pēc jūsu lūguma, vai arī septiņu dienu pļāvējs to nometa neverificētu. Divi ir par pašu apturēšanas sarakstu, kas nav tas pats, kas email.suppressed: suppression.added, kad adrese tajā nonāk, un suppression.removed, kad tā atkal ir atļauta. Neabonēt nevienu no tiem nozīmē visus ziņu notikumus, izņemot email.replied — šodien četrpadsmit, nekad ne vēlāk pievienotu saimi —, un API to nolasa atpakaļ kā ["*"]. Nosauciet vēlamos notikumus, ja labāk gribat būt skaidrs. Katra piegāde nes X-OpenEmail-Signature formā t=<unix>,v1=<hex> — HMAC-SHA-256 pār laika zīmogu, punktu un neapstrādāto pieprasījuma saturu —, kā arī X-OpenEmail-Event un X-OpenEmail-Delivery. Pārbaudiet pret baitiem tādiem, kādi tie pienāca: parsēšana un atkārtota serializēšana pārkārto atslēgas un salauž parakstu. 300 sekunžu atkārtojuma logs jāievēro saņēmējam, un SDK verificētājs to izmanto pēc noklusējuma.
Reģistrācija tiek atteikta visam, kas nav https vai nav publiski maršrutējams (loopback, RFC1918, link-local, CGNAT un to IPv6 ekvivalenti), un pāradresācijas netiek izsekotas, tāpēc 3xx tiek ierakstīts kā neizdevusies piegāde, nevis dzīts pakaļ kaut kur citur. Saņēmējam tiek dotas 5 sekundes, galapunktiem piegāde notiek paralēli, tāpēc desmit no tiem joprojām maksā 5 sekundes, nevis 50, un nesenie mēģinājumi ir uzskaitīti attiecīgā galapunkta lappusē kopā ar atbildes kodu un to, cik ilgi tas prasīja.
Piegāde tiek mēģināta līdz piecām reizēm. Pirmā aiziet notikuma brīdī; neveiksme, kas ticami varētu nokārtoties pati, tiek atkārtota pēc 1 minūtes, tad pēc 5, tad pēc 25, tad pēc 2 stundām, kas vienu notikumu izstiepj apmēram divarpus stundu garumā. Atkārtojumi tiek glabāti kā noturīgs darbs, nevis atmiņā, tāpēc izvietošana šī loga vidū tos nezaudē. Tiek atkārtotas tikai tās neveiksmes, kuras vērts atkārtot: noildze, atteikts savienojums, 408, 425, 429 vai jebkurš 5xx. Jebkurš cits 4xx nozīmē, ka galapunkts saturu noraida apzināti, un prasīt vēl četras reizes būtu četrkārtīga slodze par to pašu atbildi. Notikuma id tiek izgatavots vienreiz, un katrs mēģinājums to nes laukā X-OpenEmail-Delivery, tāpēc saņēmējs, kas vienu un to pašu id redz divreiz, otro var atmest, nevis rīkoties divreiz. Kad 100 notikumiem pēc kārtas neizdodas neviens mēģinājums, galapunkts tiek atspējots, darbvietai tiek nosūtīts e-pasts, un iemesls ir izlasāms pie paša galapunkta. Galapunkts, kas atbild ar 410 Gone, tiek atspējots uzreiz.
Galapunkts, kas neizdodas 100 reizes pēc kārtas, tiek izslēgts, nevis aptaujāts mūžīgi, un visiem, kam ir piekļuve webhooks, par to tiek nosūtīts e-pasts: kurš galapunkts, ko ziņoja pēdējais mēģinājums un ka neizdošanās laikā nekas netika likts rindā. Skaits ir PĒC KĀRTAS, un jebkurš piegādāts mēģinājums to atiestata, tāpēc viena slikta pagājušā marta pēcpusdiena nevar sasummēties līdz atspējotam galapunktam šodien. Ieslēdzot to atpakaļ, līdzi tiek notīrīts arī skaits. Konsole šos divus stāvokļus nošķir, nevis rāda vienu slēdzi: galapunkts, ko izslēdzāt jūs, izskatās citādi nekā tāds, ko izslēdzām mēs.
Galapunktu pārvaldība ir viens darbs ar divām durvīm. Caur API tas ir POST /webhooks, kā arī patch, delete, rotate-secret, test un piegāžu žurnāls, ar metodi katram no tiem SDK; lietotnē tas ir Settings → Webhooks, kas strādā ar to pašu reģistru, nevis otru. Lasīšanu ierobežo webhooks:read, tāpēc ikviens, kas veido integrāciju, var redzēt galapunktus un to piegāžu vēsturi (kurš nostrādāja, ko atbildēja saņēmējs, cik ilgi tas prasīja), nebūdams īpašnieks. Reģistrēšanai, rediģēšanai, testēšanai, rotēšanai un dzēšanai vajadzīgs webhooks:write UN pastkastes īpašumtiesības — abās virsmās —, un šī otrā puse ir apzināta: galapunktam nav adrešu ass, tāpēc tas saņem katru darbvietas adresi kopā ar tematiem un saņēmējiem, un nav tādas atļaujas, kas nozīmētu “drīkst saņemt visu to”. Loma, kas veido integrācijas un pastu nelasa, to vada ar darbvietas atslēgu.