Endpoints
`webhooks.list`, `get`, `create`, `update`, `delete`, `rotateSecret`, `test` i `listDeliveries`.
Tots els mètodes
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 és l'ÚNIC moment en què es retorna el secret, a banda de rotateSecret. Una lectura no el repeteix mai, així que desa'l abans de fer res més. Omet eventTypes per rebre tots els esdeveniments, inclosos els posteriors.
rotateSecret no té cap finestra de solapament. El secret antic deixa de funcionar immediatament, així que desplega el nou abans de rotar. Mai no es reintenta automàticament: un reintent rotaria una segona vegada i invalidaria el secret que va retornar el primer intent.
A què et pots subscriure
WEBHOOK_EVENTS s'exporta perquè puguis renderitzar-ne la llista. Els esdeveniments són esdeveniments de la **bústia**, no d'aquesta API: email.received es dispara per al correu que arriba a l'aplicació, i email.sent es dispara per a un missatge que ha enviat el redactor. Subscriure-s'hi no és el mateix que vigilar el teu propi trànsit d'API.
Comprovar que funciona
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)Un responseCode igual a null vol dir que no hi va haver cap resposta (DNS, TLS, un temps d'espera esgotat), que és un fet diferent d'una resposta que deia 0. Cada fila porta attempt i maxAttempts, de manera que diverses files poden descriure un mateix esdeveniment: el mateix payload.id en totes elles és l'esdeveniment, i el número d'intent és la provatura.
Paràmetres: webhooks.create
urlstringobligatori- On s'envien els lliuraments amb POST. Només HTTPS, i l'amfitrió no pot ser `localhost`, un nom `.localhost`/`.local`/`.internal`, ni una IP literal de loopback, privada, CGNAT o link-local. Això és una petició des del servidor a una adreça que proporciones tu, així que aquests casos donen un 422 a `url`; la comprovació llegeix el nom d'amfitrió tal com s'ha escrit i mai no resol DNS. El que es desa és la serialització que fa l'analitzador d'URL del que vas enviar, de manera que `https://acme.com` es llegeix com `https://acme.com/`.
eventTypesWebhookEvent[]- Quins esdeveniments arriben a aquest endpoint: qualsevol dels noms de `WEBHOOK_EVENTS`. `POST /webhooks` limita l'array al nombre d'esdeveniments que existeixen, de manera que un més dona un 422 a `eventTypes`; `PATCH` no el limita. Només se'n limita la longitud, i un nom repetit es desa i es torna a llegir exactament com el vas enviar. Si s'omet o és buit es desa com una llista buida, i per això es llegeix com `['*']`, i significa tots els esdeveniments `email.*` excepte `email.replied`, catorze avui, i mai les famílies de domini ni de supressió. Una família afegida més endavant no arriba mai a un endpoint que no l'hagi anomenada, de manera que una integració no pot començar a rebre una forma que no ha vist mai per culpa d'una versió nova.
descriptionstring- Una etiqueta per a l'endpoint, de 200 caràcters com a màxim, perquè una llista de webhooks es llegeixi com a noms i no com una columna d'URL. Si s'omet, es desa i es retorna com a null.
Resposta: CreatedWebhookResource
object'webhook'- Sempre `'webhook'`, el mateix discriminador que retorna una lectura normal, perquè el secret és una clau extra sobre la forma habitual i no un tipus d'objecte propi. Que `secret` hi sigui o no ho decideix el mètode que has cridat, no aquest camp.
idstring- L'identificador de l'endpoint: `whe_` seguit de 24 caràcters hexadecimals. Totes les altres crides de webhook l'accepten: `get`, `update`, `delete`, `rotateSecret`, `test` i `listDeliveries`.
urlstring- L'endpoint tal com s'ha desat, un cop superades les comprovacions d'HTTPS i d'amfitrions bloquejats. És la URL analitzada i tornada a serialitzar, així que compara amb aquest valor i no amb la cadena que vas enviar.
descriptionstring | null- L'etiqueta que li vas donar, o null si no en vas donar cap. Un `update` que envia un null explícit la torna a deixar a null.
eventTypesWebhookEvent[] | ['*']- Els esdeveniments subscrits, o `['*']` quan l'endpoint no en va anomenar cap. `['*']` és com es representa en lectura una llista desada buida i no es pot tornar a enviar, i representa els tretze esdeveniments de missatge i no pas tot el catàleg. `create` i `update` només accepten els noms literals dels esdeveniments.
enabledboolean- Si s'intenten els lliuraments; un endpoint desactivat s'omet quan es despatxen esdeveniments i conserva el seu secret i el seu historial de lliuraments. Aquí sempre és true, ja que `WebhookCreate` no té `enabled` i només `WebhookPatch` en té.
lastDeliveryAtstring | null- Marca de temps ISO 8601 de l'últim INTENT de lliurament, no de l'últim èxit. També s'estampa després d'un POST fallit, de manera que et diu que s'ha provat l'endpoint i `listDeliveries` et diu com ha anat. És null fins al primer intent i, per tant, sempre null a `create`.
createdAtstring- Marca de temps ISO 8601 de quan es va registrar l'endpoint. `list` retorna els endpoints del més nou al més antic segons aquest camp.
secretstring- La clau HMAC-SHA-256 que signa el `X-OpenEmail-Signature` de cada lliurament: `whsec_` seguit de 32 bytes aleatoris en base64url, i el que passes a `verifyWebhookSignature`. La retornen `create` i `rotateSecret` i res més. Una lectura no el repeteix mai, així que desa'l ara; un secret perdut només es pot substituir amb `rotateSecret`, que invalida l'antic immediatament.