Endpoint-et
`webhooks.list`, `get`, `create`, `update`, `delete`, `rotateSecret`, `test` dhe `listDeliveries`.
Çdo metodë
const endpoint = await openemail.webhooks.create({ url: 'https://acme.com/hooks/mail', eventTypes: ['email.sent', 'email.bounced'], description: 'Billing service',}) await store(endpoint.secret) await openemail.webhooks.list()await openemail.webhooks.get(endpoint.id)await openemail.webhooks.update(endpoint.id, { enabled: false })await openemail.webhooks.test(endpoint.id)const rotated = await openemail.webhooks.rotateSecret(endpoint.id)await openemail.webhooks.delete(endpoint.id)create është hera E VETME kur kthehet sekreti, përveç rotateSecret. Një lexim nuk e kthen kurrë, ndaj ruajeni para se të bëni çdo gjë tjetër. Lëreni jashtë eventTypes për të marrë çdo ngjarje, përfshirë edhe ato të mëvonshmet.
rotateSecret nuk ka dritare mbivendosjeje. Sekreti i vjetër pushon së funksionuari menjëherë, ndaj vendoseni të riun në prodhim para se të bëni rrotullimin. Nuk riprovohet kurrë automatikisht: një riprovë do të bënte një rrotullim të dytë dhe do ta bënte të pavlefshëm sekretin që ktheu përpjekja e parë.
Te çfarë mund të abonoheni
WEBHOOK_EVENTS eksportohet që ta shfaqni listën. Ngjarjet janë ngjarje të **kutisë postare**, jo të kësaj API: email.received aktivizohet për postën që mbërrin në aplikacion, kurse email.sent aktivizohet për një mesazh që e dërgoi hartuesi. Abonimi nuk është e njëjta gjë me vëzhgimin e trafikut tuaj të API-së.
Si provohet se funksionon
const result = await openemail.webhooks.test('whe_…')console.log(result.delivery?.status, result.delivery?.responseCode) const deliveries = await openemail.webhooks.listDeliveries('whe_…')for (const d of deliveries) console.log(d.eventType, d.status, d.responseCode, d.error)Një responseCode i barabartë me null do të thotë se nuk pati fare përgjigje (DNS, TLS, një timeout), që është fakt tjetër nga një përgjigje që tha 0. Çdo rresht mbart attempt dhe maxAttempts, ndaj disa rreshta mund të përshkruajnë një ngjarje të vetme: i njëjti payload.id në të gjithë ata është ngjarja, kurse numri i përpjekjes është prova.
Parametrat: webhooks.create
urlstringe detyrueshme- Ku POST-ohen dërgesat. Vetëm HTTPS, dhe host-i nuk mund të jetë `localhost`, një emër `.localhost`/`.local`/`.internal`, apo një IP literale loopback, private, CGNAT ose link-local. Kjo është një kërkesë nga ana e serverit drejt një adrese që e jepni ju, ndaj ato janë një 422 te `url`; kontrolli e lexon emrin e host-it ashtu siç është shkruar dhe nuk zgjidh kurrë DNS. Ajo që ruhet është serializimi i parserit të URL-së për atë që dërguat, ndaj `https://acme.com` lexohet prapë si `https://acme.com/`.
eventTypesWebhookEvent[]- Cilat ngjarje mbërrijnë te ky endpoint: cilido prej emrave te `WEBHOOK_EVENTS`. `POST /webhooks` e kufizon array-n te numri i ngjarjeve që ekzistojnë, ndaj një më shumë se aq është një 422 te `eventTypes`; `PATCH` nuk e kufizon. Kufizohet vetëm gjatësia, kurse një emër i përsëritur ruhet dhe lexohet prapë saktësisht ashtu siç e dërguat. I lënë jashtë ose bosh, ruhet si listë bosh, prandaj lexohet prapë si `['*']`, dhe do të thotë çdo ngjarje `email.*` përveç `email.replied`, katërmbëdhjetë sot, dhe kurrë familjet domain ose suppression. Një familje e shtuar më vonë nuk mbërrin kurrë te një endpoint që nuk e ka emërtuar, ndaj një integrim nuk mund të nisë të marrë një formë që nuk e ka parë kurrë, thjesht për shkak të një publikimi.
descriptionstring- Një etiketë për endpoint-in, me më së shumti 200 karaktere, që një listë webhook-esh të lexohet si emra e jo si një kolonë URL-sh. Nëse lihet jashtë, ruhet dhe kthehet si null.
Përgjigjja: CreatedWebhookResource
object'webhook'- Gjithmonë `'webhook'`, i njëjti diskriminues që kthen një lexim i thjeshtë, sepse sekreti është një çelës shtesë mbi formën e zakonshme e jo një tip objekti më vete. Nëse `secret` është i pranishëm apo jo, vendoset nga metoda që thirrët, jo nga kjo fushë.
idstring- Identifikuesi i endpoint-it: `whe_` i ndjekur nga 24 karaktere hex. E marrin të gjitha thirrjet e tjera të webhook-ut: `get`, `update`, `delete`, `rotateSecret`, `test` dhe `listDeliveries`.
urlstring- Endpoint-i ashtu siç është ruajtur, pasi ka kaluar kontrollet e HTTPS dhe të host-eve të bllokuar. Është URL-ja e parsuar e riserializuar, ndaj krahasoni me këtë vlerë e jo me vargun që dërguat.
descriptionstring | null- Etiketa që i vutë, ose null nëse nuk i vutë asnjë. Një `update` që dërgon një null të shprehur e pastron atë sërish në null.
eventTypesWebhookEvent[] | ['*']- Ngjarjet e abonuara, ose `['*']` kur endpoint-i nuk emërtoi asnjë. `['*']` është mënyra si shfaqet në lexim një listë e ruajtur bosh dhe nuk mund të dërgohet prapë; ai qëndron për të trembëdhjetë ngjarjet e mesazheve e jo për gjithë katalogun. `create` dhe `update` pranojnë vetëm emrat literalë të ngjarjeve.
enabledboolean- Nëse tentohen dërgesat; një endpoint i çaktivizuar anashkalohet kur shpërndahen ngjarjet dhe e ruan sekretin e vet e historikun e dërgesave. Gjithmonë true këtu, meqë `WebhookCreate` nuk ka `enabled` dhe e ka vetëm `WebhookPatch`.
lastDeliveryAtstring | null- Vula kohore ISO 8601 e PËRPJEKJES së fundit për dërgesë, jo e suksesit të fundit. Ajo vihet edhe pas një POST-i të dështuar, ndaj ju thotë se endpoint-i u provua, kurse `listDeliveries` ju thotë si shkoi. Null derisa të bëhet përpjekja e parë, prandaj gjithmonë null te `create`.
createdAtstring- Vula kohore ISO 8601 e çastit kur u regjistrua endpoint-i. `list` i kthen endpoint-et nga më i riu te më i vjetri sipas kësaj fushe.
secretstring- Çelësi HMAC-SHA-256 që nënshkruan `X-OpenEmail-Signature`-n e çdo dërgese: `whsec_` i ndjekur nga 32 bajt të rastësishëm në base64url, dhe ai që i jepni `verifyWebhookSignature`. Kthehet nga `create` dhe `rotateSecret` e nga asgjë tjetër. Një lexim nuk e kthen kurrë, ndaj ruajeni tani; një sekret i humbur mund të zëvendësohet vetëm me `rotateSecret`, që e bën të pavlefshëm të vjetrin menjëherë.