Endpoints
`webhooks.list`, `get`, `create`, `update`, `delete`, `rotateSecret`, `test` e `listDeliveries`.
Todos os 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 é a ÚNICA altura em que o segredo é devolvido, além de rotateSecret. Uma leitura nunca o repete, por isso guarde-o antes de fazer mais alguma coisa. Omita eventTypes para receber todos os eventos, incluindo os que vierem depois.
rotateSecret não tem janela de sobreposição. O segredo antigo deixa de funcionar imediatamente, por isso coloque o novo em produção antes de rodar. Nunca é repetido automaticamente: uma repetição rodaria uma segunda vez e invalidaria o segredo que a primeira tentativa devolveu.
A que pode subscrever
WEBHOOK_EVENTS é exportado para que possa desenhar a lista. Os eventos são eventos da **caixa de correio**, não desta API: email.received dispara para o correio que chega à aplicação, e email.sent dispara para uma mensagem enviada pelo compositor. Subscrever não é o mesmo que observar o seu próprio tráfego de API.
Provar 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)Um responseCode a null significa que não houve resposta nenhuma (DNS, TLS, um timeout), o que é um facto diferente de uma resposta que disse 0. Cada linha leva attempt e maxAttempts, por isso várias linhas podem descrever um só evento: o mesmo payload.id entre elas é o evento, e o número da tentativa é a tentativa.
Parâmetros: webhooks.create
urlstringobrigatório- Para onde as entregas são feitas por POST. Apenas HTTPS, e o host não pode ser `localhost`, um nome `.localhost`/`.local`/`.internal`, nem um literal de IP de loopback, privado, CGNAT ou link-local. Isto é um fetch do lado do servidor para um endereço que você fornece, por isso esses são um 422 em `url`; a verificação lê o hostname tal como foi escrito e nunca resolve DNS. O que fica armazenado é a serialização, feita pelo parser de URL, daquilo que enviou, por isso `https://acme.com` lê-se de volta como `https://acme.com/`.
eventTypesWebhookEvent[]- Que eventos chegam a este endpoint: quaisquer dos nomes em `WEBHOOK_EVENTS`. `POST /webhooks` limita o array ao número de eventos que existem, por isso um a mais é um 422 em `eventTypes`; `PATCH` não o limita. Só o comprimento é limitado, e um nome repetido é armazenado e lido de volta exatamente como o enviou. Omitido ou vazio é armazenado como uma lista vazia, que é a razão de se ler de volta como `['*']`, e significa todos os eventos `email.*` menos `email.replied`, catorze hoje, e nunca as famílias de domínio ou de supressão. Uma família acrescentada mais tarde nunca chega a um endpoint que não a nomeou, para que uma integração não possa começar a receber uma forma que nunca viu por causa de um lançamento.
descriptionstring- Uma etiqueta para o endpoint, com 200 caracteres no máximo, para que uma lista de webhooks se leia como nomes em vez de uma coluna de URLs. Omitida, é armazenada e devolvida como null.
Resposta: CreatedWebhookResource
object'webhook'- Sempre `'webhook'`, o mesmo discriminador que uma leitura simples devolve, porque o `secret` é uma chave a mais na forma habitual e não um tipo de objeto próprio. Se `secret` está presente decide-se pelo método que chamou, não por este campo.
idstring- O identificador do endpoint: `whe_` seguido de 24 caracteres hexadecimais. Todas as outras chamadas de webhook o recebem: `get`, `update`, `delete`, `rotateSecret`, `test` e `listDeliveries`.
urlstring- O endpoint tal como ficou armazenado, depois de passar as verificações de HTTPS e de hosts bloqueados. É o URL analisado e novamente serializado, por isso compare com este valor e não com a string que enviou.
descriptionstring | null- A etiqueta que lhe deu, ou null se não deu nenhuma. Um `update` que envie um null explícito limpa-a de volta para null.
eventTypesWebhookEvent[] | ['*']- Os eventos subscritos, ou `['*']` quando o endpoint não nomeou nenhum. `['*']` é como uma lista vazia armazenada é apresentada na leitura e não pode ser enviado de volta, e representa os treze eventos de mensagem e não o catálogo inteiro. `create` e `update` aceitam apenas os nomes literais dos eventos.
enabledboolean- Se as entregas são tentadas; um endpoint desativado é saltado quando os eventos são despachados e mantém o seu segredo e o seu histórico de entregas. Aqui é sempre true, uma vez que `WebhookCreate` não tem `enabled` e só `WebhookPatch` tem.
lastDeliveryAtstring | null- Timestamp ISO 8601 da última TENTATIVA de entrega, e não do último sucesso. É carimbado também depois de um POST falhado, por isso diz-lhe que o endpoint foi tentado e `listDeliveries` diz-lhe como correu. Null até à primeira tentativa, e por isso sempre null no `create`.
createdAtstring- Timestamp ISO 8601 de quando o endpoint foi registado. `list` devolve os endpoints do mais recente para o mais antigo por este campo.
secretstring- A chave HMAC-SHA-256 que assina o `X-OpenEmail-Signature` de cada entrega: `whsec_` seguido de 32 bytes aleatórios em base64url, e o que entrega a `verifyWebhookSignature`. Devolvida por `create` e `rotateSecret` e por mais nada. Uma leitura nunca a repete, por isso guarde-a já; um segredo perdido só pode ser substituído com `rotateSecret`, que invalida o antigo imediatamente.