Baza e njohurive

Webhook-et

I tregon endpoint-it tuaj kur mbërrin postë, në vend që t'ju detyrojë të pyesni vazhdimisht.

Hollësi

I përdorshëm që sot nga Cilësimet → Webhooks dhe përmes API-së: regjistroni një endpoint https, zgjidhni cilat nga njëzet ngjarjet dëshiron, dhe kopjoni sekretin e nënshkrimit whsec_, i cili shfaqet vetëm në krijim dhe në rrotullim e kurrë më. Dorëzimet janë POST-e reale të nënshkruara, të ngritura nga vetë kutia postare dhe jo nga ndonjë thirrje API, ndaj ato ndizen për postën hyrëse dhe për hapjet e klikimet, pavarësisht se çfarë e dërgoi mesazhin. Dërgimi ndizet nga çdo sipërfaqe, ndërsa dikur ndizej vetëm nga disa: një dërgim përmes API-së, MCP-së, një shablloni ose një rregulli ngrinte email.sent, ndërsa një mesazh i dërguar nga hartuesi i vetë aplikacionit jo, sepse hartuesi i shkruan drejtpërdrejt kutisë postare dhe jo përmes shërbimit të dërgimit që e nxirrte ngjarjen. Ngjarja tani ngrihet te vetë kutia postare, ku takohen të gjitha, ndaj hartimi në aplikacion, planifikimi për të martën dhe postimi te API-ja janë tri mënyra për të shkaktuar të njëjtin webhook. Një dërgim i shtyrë e thotë dy herë: email.scheduled ose email.queued kur pranohet, email.sent kur niset vërtet, dhe email.cancelled nëse e tërhiqni ndërkohë. Dhjetë endpoint-e për çdo kuti postare, të zbatuara kudo ku regjistrohet një i tillë dhe jo vetëm në këtë ekran.
Ngjarjet vijnë në tri familje. Pesëmbëdhjetë kanë të bëjnë me një mesazh të vetëm: email.received, email.replied, email.sent, email.delivered, email.failed, email.cancelled, email.scheduled, email.queued (motra e email.scheduled për zhbërjen e dërgimit), email.delivery_delayed, email.bounced, email.complained, email.suppressed, email.opened, email.clicked dhe email.downloaded. email.sent do të thotë se shërbimi i dërgimit e pranoi mesazhin, email.delivered do të thotë se e pranoi serveri marrës, dhe email.delivery_delayed do të thotë se ai nuk ka mbërritur ende dhe po riprovohet. email.replied ndizet krahas email.received kur mesazhi që mbërrin i përgjigjet një mesazhi që ndodhet tashmë në kutinë postare, ndaj një konsumues që i do të dyja i merr të dyja. email.downloaded ndizet kur një person merr një skedar që doli si lidhje shkarkimi, me të njëjtin klasifikues që i mban jashtë numërimit skanuesit dhe parapamjet e lidhjeve, dhe ajo nuk emërton asnjë marrës, sepse lidhja është e njëjta për të gjithë ata te të cilët shkoi mesazhi. Tri kanë të bëjnë me një domen: domain.verified kur ai fillon të marrë postë, domain.sending_changed kur verdikti i tij për dërgimin ndryshon, dhe domain.deleted kur ai hiqet, qoftë sepse e kërkuat ju, qoftë sepse e hoqi i paverifikuar pastruesi shtatëditor. Dy kanë të bëjnë me vetë listën e përjashtimeve, e cila është diçka tjetër nga email.suppressed: suppression.added kur një adresë futet aty, suppression.removed kur një adresë lejohet sërish. Të mos abonohesh në asnjërën do të thotë çdo ngjarje mesazhi përveç email.replied, katërmbëdhjetë sot, kurrë një familje e shtuar më vonë, dhe API-ja e lexon këtë mbrapsht si ["*"]. Emërtoni ngjarjet që doni nëse preferoni të jeni i qartë. Çdo dorëzim mban X-OpenEmail-Signature në formën t=<unix>,v1=<hex>, një HMAC-SHA-256 mbi vulën kohore, një pikë dhe trupin e papërpunuar, plus X-OpenEmail-Event dhe X-OpenEmail-Delivery. Verifikoni ndaj bajtëve ashtu siç mbërritën: analizimi dhe riserializimi i rirendit çelësat dhe e prish nënshkrimin. Dritarja e ripërsëritjes prej 300 sekondash është e marrësit për ta zbatuar, dhe verifikuesi i SDK-së e përdor si parazgjedhje.
Regjistrimi refuzohet për çdo gjë që nuk është https ose që nuk është e rrugëzueshme publikisht (loopback, RFC1918, link-local, CGNAT dhe ekuivalentët IPv6), dhe ridrejtimet nuk ndiqen, ndaj një 3xx regjistrohet si dorëzim i dështuar dhe nuk ndiqet diku tjetër. Marrësi ka 5 sekonda, endpoint-et dorëzohen paralelisht, ndaj dhjetë prej tyre kushtojnë prapë 5 sekonda dhe jo 50, ndërsa provat e fundit listohen në faqen e atij endpoint-i me kodin e përgjigjes dhe kohën që zgjati.
Një dorëzim provohet deri në pesë herë. I pari niset në çastin që ndodh ngjarja; një dështim që mund të kalojë vetvetiu riprovohet pas 1 minute, pastaj 5, pastaj 25, pastaj 2 orësh, gjë që e shtrin një ngjarje të vetme në rreth dy orë e gjysmë. Riprovat mbahen si punë e qëndrueshme dhe jo në memorie, ndaj një publikim i ri në mes të asaj dritareje nuk i humb. Përsëriten vetëm dështimet që ia vlen t'i përsërisësh: një skadencë kohore, një lidhje e refuzuar, 408, 425, 429 ose çdo 5xx. Çdo 4xx tjetër është endpoint-i që e refuzon qëllimisht ngarkesën, dhe të pyesje edhe katër herë do të ishte katërfishi i ngarkesës për të njëjtën përgjigje. Id-ja e ngjarjes krijohet një herë dhe çdo provë e mban te X-OpenEmail-Delivery, ndaj një marrës që sheh dy herë të njëjtën id mund ta hedhë të dytën në vend që të veprojë dy herë. Pasi 100 ngjarje radhazi dështojnë në çdo provë, endpoint-i çaktivizohet, hapësirës së punës i dërgohet email, dhe arsyeja lexohet te vetë endpoint-i. Një endpoint që përgjigjet me 410 Gone çaktivizohet në vend.
Një endpoint që dështon 100 herë radhazi fiket, në vend që të thirret përgjithmonë, dhe të gjithëve me akses te webhook-et u dërgohet email për ta thënë këtë: cili është, çfarë raportoi prova e fundit, dhe që asgjë nuk u vendos në radhë ndërsa ai dështonte. Numërimi është I NJËPASNJËSHËM dhe çdo provë e dorëzuar e rinis nga e para, ndaj një pasdite e keqe marsin e kaluar nuk mund të mblidhet e të çojë te një endpoint i çaktivizuar sot. Rindezja e tij e pastron bashkë me të edhe numërimin. Konsola i dallon dy gjendjet në vend që të shfaqë një çelës të vetëm: një endpoint që e fikët ju duket ndryshe nga një që e fikëm ne.
Menaxhimi i endpoint-eve është një punë e vetme me dy dyer hyrëse. Përmes API-së është POST /webhooks, patch-i, delete-i, rotate-secret, test dhe regjistri i dorëzimeve, me nga një metodë për secilin në SDK; në aplikacion është Cilësimet → Webhooks, mbi të njëjtin regjistër dhe jo mbi një të dytë. Leximi kushtëzohet nga webhooks:read, ndaj kushdo që po ndërton një integrim mund t'i shohë endpoint-et dhe historikun e tyre të dorëzimeve (cili u ndez, çfarë u përgjigj marrësi, sa zgjati) pa qenë pronari. Regjistrimi, redaktimi, testimi, rrotullimi dhe fshirja kërkojnë webhooks:write DHE pronësinë e kutisë postare, në të dyja sipërfaqet, dhe kjo pjesa e dytë është e qëllimshme: një endpoint nuk ka bosht adresash, ndaj ai merr çdo adresë që mban hapësira e punës bashkë me subjektet dhe marrësit, dhe asnjë leje nuk do të thotë “mund t'i dërgohet e gjithë kjo”. Një rol që ndërton integrime dhe nuk e lexon postën e drejton këtë me një çelës hapësire pune.