Endpoints
`webhooks.list`, `get`, `create`, `update`, `delete`, `rotateSecret`, `test` y `listDeliveries`.
Todos los métodos
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 es la ÚNICA ocasión en que se devuelve el secreto, aparte de rotateSecret. Una lectura nunca lo repite, así que guárdalo antes de hacer cualquier otra cosa. Omite eventTypes para recibir todos los eventos, incluidos los posteriores.
rotateSecret no tiene ventana de solapamiento. El secreto antiguo deja de funcionar de inmediato, así que despliega el nuevo antes de rotar. Nunca se reintenta automáticamente: un reintento rotaría por segunda vez e invalidaría el secreto que devolvió el primer intento.
A qué puedes suscribirte
WEBHOOK_EVENTS se exporta para que puedas mostrar la lista. Los eventos son eventos del **buzón**, no de esta API: email.received se dispara con el correo que llega a la aplicación, y email.sent se dispara con un mensaje que envió el redactor. Suscribirse no es lo mismo que observar tu propio tráfico de API.
Comprobar 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 de null significa que no hubo respuesta alguna (DNS, TLS, un tiempo de espera agotado), que es un hecho distinto de una respuesta que dijo 0. Cada fila lleva attempt y maxAttempts, así que varias filas pueden describir un mismo evento: el payload.id compartido entre ellas identifica el evento, y el número de intento identifica cada envío.
Parámetros: webhooks.create
urlstringobligatorio- A dónde se hace POST de las entregas. Solo HTTPS, y el host no puede ser `localhost`, un nombre `.localhost`/`.local`/`.internal`, ni un literal de IP de loopback, privada, CGNAT o link-local. Esto es una petición desde el servidor a una dirección que tú indicas, así que esos casos son un 422 sobre `url`; la comprobación lee el nombre de host tal como está escrito y nunca resuelve DNS. Lo que se almacena es la serialización que hace el analizador de URL de lo que enviaste, así que `https://acme.com` se lee de vuelta como `https://acme.com/`.
eventTypesWebhookEvent[]- Qué eventos llegan a este endpoint: cualquiera de los nombres de `WEBHOOK_EVENTS`. `POST /webhooks` limita el array al número de eventos que existen, así que uno más es un 422 sobre `eventTypes`; `PATCH` no lo limita. Solo se limita la longitud, y un nombre repetido se almacena y se lee de vuelta exactamente como lo enviaste. Omitido o vacío se almacena como una lista vacía, y por eso se lee de vuelta como `['*']`, y significa todos los eventos `email.*` salvo `email.replied`, catorce hoy, y nunca las familias de dominio o de supresión. Una familia añadida más tarde nunca llega a un endpoint que no la nombró, de modo que una integración no puede empezar a recibir una forma que nunca ha visto por culpa de una publicación.
descriptionstring- Una etiqueta para el endpoint, de 200 caracteres como máximo, para que una lista de webhooks se lea como nombres y no como una columna de URLs. Si se omite, se almacena y se devuelve como null.
Respuesta: CreatedWebhookResource
object'webhook'- Siempre `'webhook'`, el mismo discriminador que devuelve una lectura normal, porque el secreto es una clave extra sobre la forma habitual y no un tipo de objeto propio. Que `secret` esté presente lo decide el método que llamaste, no este campo.
idstring- El identificador del endpoint: `whe_` seguido de 24 caracteres hexadecimales. Todas las demás llamadas de webhook lo reciben: `get`, `update`, `delete`, `rotateSecret`, `test` y `listDeliveries`.
urlstring- El endpoint tal como está almacenado, tras superar las comprobaciones de HTTPS y de hosts bloqueados. Es la URL analizada y vuelta a serializar, así que compara contra este valor y no contra la cadena que enviaste.
descriptionstring | null- La etiqueta que le pusiste, o null si no pusiste ninguna. Un `update` que envía un null explícito la borra de vuelta a null.
eventTypesWebhookEvent[] | ['*']- Los eventos suscritos, o `['*']` cuando el endpoint no nombró ninguno. `['*']` es como se representa al leer una lista almacenada vacía y no puede enviarse de vuelta, y representa los trece eventos de mensaje, no el catálogo completo. `create` y `update` solo aceptan los nombres literales de los eventos.
enabledboolean- Si se intentan las entregas; un endpoint deshabilitado se omite al despachar los eventos y conserva su secreto y su historial de entregas. Aquí siempre es true, ya que `WebhookCreate` no tiene `enabled` y solo `WebhookPatch` lo tiene.
lastDeliveryAtstring | null- Marca de tiempo ISO 8601 del último INTENTO de entrega, no del último éxito. También se registra tras un POST fallido, así que te dice que se probó el endpoint, y `listDeliveries` te dice cómo fue. Null hasta el primer intento y, por tanto, siempre null en `create`.
createdAtstring- Marca de tiempo ISO 8601 de cuándo se registró el endpoint. `list` devuelve los endpoints del más reciente al más antiguo según este campo.
secretstring- La clave HMAC-SHA-256 que firma el `X-OpenEmail-Signature` de cada entrega: `whsec_` seguido de 32 bytes aleatorios en base64url, y lo que le pasas a `verifyWebhookSignature`. La devuelven `create` y `rotateSecret`, y nada más. Una lectura nunca lo repite, así que guárdalo ahora; un secreto perdido solo puede reemplazarse con `rotateSecret`, que invalida el antiguo de inmediato.