Galapunkti
`webhooks.list`, `get`, `create`, `update`, `delete`, `rotateSecret`, `test` un `listDeliveries`.
Katra metode
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 ir VIENĪGĀ reize, kad noslēpums tiek atgriezts, ja neskaita rotateSecret. Lasījums to nekad neatkārto, tāpēc saglabā to, pirms dari ko citu. Izlaid eventTypes, lai saņemtu katru notikumu, arī vēlāk pievienotos.
rotateSecret pārklāšanās loga nav. Vecais noslēpums pārstāj darboties uzreiz, tāpēc izvieto jauno, pirms rotē. Tas nekad netiek atkārtots automātiski: atkārtojums rotētu otrreiz un anulētu noslēpumu, ko atgrieza pirmais mēģinājums.
Uz ko var parakstīties
WEBHOOK_EVENTS tiek eksportēts, lai tu varētu attēlot sarakstu. Notikumi ir **pastkastes** notikumi, nevis šī API notikumi: email.received nostrādā pastam, kas nonāk lietotnē, un email.sent nostrādā ziņojumam, ko nosūtīja redaktors. Parakstīšanās nav tas pats, kas savas API datplūsmas vērošana.
Kā pārliecināties, ka tas strādā
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)responseCode ar vērtību null nozīmē, ka atbildes nebija vispār (DNS, TLS, noildze), un tas ir cits fakts nekā atbilde, kas teica 0. Katra rinda nes attempt un maxAttempts, tāpēc vairākas rindas var aprakstīt vienu notikumu: vienāds payload.id tajās ir notikums, un mēģinājuma numurs ir mēģinājums.
Parametri: webhooks.create
urlstringobligāts- Kurp piegādes tiek POSTotas. Tikai HTTPS, un resursdators nedrīkst būt `localhost`, `.localhost`/`.local`/`.internal` nosaukums vai cilpas, privāta, CGNAT vai saites lokāla IP adrese burtiskā formā. Šis ir servera puses fetch uz adresi, ko norādi tu, tāpēc tie ir 422 uz `url`; pārbaude nolasa resursdatora nosaukumu tādu, kāds uzrakstīts, un nekad neatrisina DNS. Tiek saglabāta URL parsētāja serializācija tam, ko nosūtīji, tāpēc `https://acme.com` nolasās atpakaļ kā `https://acme.com/`.
eventTypesWebhookEvent[]- Kuri notikumi sasniedz šo galapunktu: jebkurš no nosaukumiem `WEBHOOK_EVENTS`. `POST /webhooks` ierobežo masīvu līdz esošo notikumu skaitam, tāpēc par vienu vairāk ir 422 uz `eventTypes`; `PATCH` to neierobežo. Ierobežots ir tikai garums, un atkārtots nosaukums tiek saglabāts un nolasīts atpakaļ tieši tāds, kādu to nosūtīji. Izlaists vai tukšs tiek saglabāts kā tukšs saraksts, tāpēc tas nolasās atpakaļ kā `['*']`, un tas nozīmē katru `email.*` notikumu, izņemot `email.replied` — šodien četrpadsmit —, un nekad ne domēnu vai apspiešanas saimi. Vēlāk pievienota saime nekad nesasniedz galapunktu, kas to nav nosaucis, tāpēc integrācija laidiena dēļ nevar sākt saņemt formu, kādu tā nekad nav redzējusi.
descriptionstring- Galapunkta apzīmējums, ne garāks par 200 rakstzīmēm, lai webhook saraksts lasītos kā nosaukumi, nevis kā URL kolonna. Ja izlaists, tas tiek saglabāts un atgriezts kā null.
Atbilde: CreatedWebhookResource
object'webhook'- Vienmēr `'webhook'` — tas pats diskriminators, ko atgriež parasts lasījums, jo noslēpums ir viena papildu atslēga uz parastās formas, nevis savs objekta tips. To, vai `secret` ir klāt, izšķir tas, kuru metodi izsauci, nevis šis lauks.
idstring- Galapunkta identifikators: `whe_`, kam seko 24 heksadecimālas rakstzīmes. To pieņem katrs cits webhook izsaukums: `get`, `update`, `delete`, `rotateSecret`, `test` un `listDeliveries`.
urlstring- Galapunkts tāds, kāds saglabāts, izturējis HTTPS un bloķēto resursdatoru pārbaudes. Tas ir no jauna serializēts parsētais URL, tāpēc salīdzini ar šo vērtību, nevis ar virkni, ko nosūtīji.
descriptionstring | null- Apzīmējums, ko tam devi, vai null, ja nedevi nevienu. `update`, kas nosūta skaidru null, to notīra atpakaļ uz null.
eventTypesWebhookEvent[] | ['*']- Abonētie notikumi vai `['*']`, kad galapunkts nav nosaucis nevienu. `['*']` ir veids, kā lasījumā tiek attēlots tukšs saglabātais saraksts, un to nevar nosūtīt atpakaļ; tas apzīmē trīspadsmit ziņojumu notikumus, nevis visu katalogu. `create` un `update` pieņem tikai burtiskus notikumu nosaukumus.
enabledboolean- Vai piegādes tiek mēģinātas; atspējots galapunkts, izsūtot notikumus, tiek izlaists un patur savu noslēpumu un piegāžu vēsturi. Šeit vienmēr true, jo `WebhookCreate` nav `enabled` un tas ir tikai `WebhookPatch`.
lastDeliveryAtstring | null- ISO 8601 laikspiedols pēdējam piegādes MĒĢINĀJUMAM, nevis pēdējai veiksmei. Tas tiek uzspiests arī pēc neveiksmīga POST, tāpēc tas pasaka, ka galapunkts tika mēģināts, un `listDeliveries` pasaka, kā gāja. Null līdz pirmajam mēģinājumam, tātad `create` gadījumā vienmēr null.
createdAtstring- ISO 8601 laikspiedols, kad galapunkts tika reģistrēts. `list` atgriež galapunktus pēc šī lauka, jaunākos vispirms.
secretstring- HMAC-SHA-256 atslēga, kas paraksta katras piegādes `X-OpenEmail-Signature`: `whsec_`, kam seko 32 nejauši baiti base64url kodējumā, un tā, ko padod `verifyWebhookSignature`. To atgriež `create` un `rotateSecret` un nekas cits. Lasījums to nekad neatkārto, tāpēc saglabā to tagad; pazaudētu noslēpumu var aizstāt tikai ar `rotateSecret`, kas veco anulē nekavējoties.