Base de conhecimento

Webhooks

Avisam o seu endpoint quando chega correio, em vez de o obrigarem a sondar.

Detalhes

Utilizáveis hoje a partir de Definições → Webhooks e pela API: registe um endpoint https, escolha quais dos vinte eventos quer, e copie o segredo de assinatura whsec_, que é mostrado na criação e na rotação e nunca mais. As entregas são POSTs assinados a sério, levantados pela própria caixa de correio e não por qualquer chamada à API, pelo que disparam com o correio a entrar e com aberturas e cliques, seja o que for que tenha enviado a mensagem. O envio dispara a partir de todas as superfícies, e houve tempo em que só disparava a partir de algumas: um envio pela API, por MCP, por um modelo ou por uma regra levantava email.sent, enquanto uma mensagem enviada pelo editor da própria aplicação não o fazia, porque o editor escreve diretamente na caixa de correio em vez de passar pelo serviço de envio que emitia o evento. O evento é agora levantado na própria caixa de correio, que é onde todos se encontram, pelo que escrever na aplicação, agendar para terça-feira e publicar na API são três formas de causar o mesmo webhook. Um envio adiado di-lo duas vezes: email.scheduled ou email.queued quando é aceite, email.sent quando sai mesmo, e email.cancelled se o retirar entretanto. Dez endpoints por caixa de correio, aplicados onde quer que um seja registado e não apenas neste ecrã.
Os eventos vêm em três famílias. Quinze dizem respeito a uma mensagem: email.received, email.replied, email.sent, email.delivered, email.failed, email.cancelled, email.scheduled, email.queued (o irmão de scheduled para anular o envio), email.delivery_delayed, email.bounced, email.complained, email.suppressed, email.opened, email.clicked e email.downloaded. email.sent significa que o serviço de envio aceitou a mensagem, email.delivered significa que o servidor recetor a aceitou, e email.delivery_delayed significa que ainda não chegou e que continua a ser tentada. email.replied dispara ao lado de email.received quando a mensagem que chega responde a uma que já está na caixa de correio, pelo que um consumidor que queira ambos recebe ambos. email.downloaded dispara quando uma pessoa obtém um ficheiro que saiu como ligação de transferência, com o mesmo classificador a manter os scanners e os pré-visualizadores de ligações fora da contagem, e não nomeia nenhum destinatário, porque a ligação é a mesma para toda a gente a quem a mensagem foi. Três dizem respeito a um domínio: domain.verified quando começa a receber, domain.sending_changed quando o seu veredicto de envio muda, e domain.deleted quando é removido, quer tenha pedido, quer o processo de limpeza ao fim de sete dias o tenha largado por verificar. Dois dizem respeito à própria lista de supressão, que é coisa diferente de email.suppressed: suppression.added quando um endereço entra, suppression.removed quando um volta a ser permitido. Não subscrever nenhum deles significa todos os eventos de mensagem exceto email.replied, catorze hoje, nunca uma família acrescentada depois, e a API devolve isso como ["*"]. Nomeie os eventos que quer se preferir ser explícito. Cada entrega leva X-OpenEmail-Signature no formato t=<unix>,v1=<hex>, um HMAC-SHA-256 sobre o carimbo temporal, um ponto e o corpo em bruto, mais X-OpenEmail-Event e X-OpenEmail-Delivery. Verifique contra os bytes tal como chegaram: analisar e voltar a serializar reordena as chaves e quebra a assinatura. A janela de repetição de 300 segundos é da responsabilidade de quem recebe, e o verificador do SDK usa-a por predefinição.
O registo é recusado para tudo o que não seja https ou não seja encaminhável publicamente (loopback, RFC1918, link-local, CGNAT e os equivalentes em IPv6), e os redirecionamentos não são seguidos, pelo que um 3xx é registado como entrega falhada em vez de ser perseguido para outro lado. Quem recebe tem 5 segundos, os endpoints são entregues em paralelo, pelo que dez deles continuam a custar 5 segundos e não 50, e as tentativas recentes são listadas na página desse endpoint com o código de resposta e o tempo que demorou.
Uma entrega é tentada até cinco vezes. A primeira sai no momento em que o evento acontece; uma falha que possa plausivelmente resolver-se sozinha é repetida ao fim de 1 minuto, depois 5, depois 25, depois 2 horas, o que espalha um evento por cerca de duas horas e meia. As repetições são guardadas como trabalho durável e não em memória, pelo que uma implementação a meio dessa janela não as perde. Só se repetem as falhas que vale a pena repetir: um tempo-limite, uma ligação recusada, 408, 425, 429 ou qualquer 5xx. Qualquer outro 4xx é o endpoint a rejeitar deliberadamente o conteúdo, e pedir mais quatro vezes seria quatro vezes a carga para a mesma resposta. O id do evento é criado uma vez e todas as tentativas o levam em X-OpenEmail-Delivery, pelo que um recetor que veja o mesmo id duas vezes pode descartar o segundo em vez de agir duas vezes. Depois de 100 eventos seguidos falharem todas as tentativas, o endpoint é desativado, o espaço de trabalho recebe um email, e o motivo fica legível no próprio endpoint. Um endpoint que responda 410 Gone é desativado de imediato.
Um endpoint que falhe 100 vezes seguidas é desligado em vez de ser marcado para sempre, e toda a gente com acesso a webhooks recebe um email a dizê-lo: qual deles, o que reportou a última tentativa, e que nada ficou em fila enquanto estava a falhar. A contagem é CONSECUTIVA e qualquer tentativa entregue põe-na a zero, pelo que uma tarde má em março passado não pode somar-se a um endpoint desativado hoje. Voltar a ligá-lo limpa a contagem com ele. A consola distingue os dois estados em vez de mostrar um único interruptor: um endpoint que desligou tem um aspeto diferente de um que nós desligámos.
Gerir endpoints é um só trabalho com duas portas de entrada. Pela API é POST /webhooks, o patch, o delete, rotate-secret, test e o registo de entregas, com um método para cada no SDK; na aplicação é Definições → Webhooks, contra o mesmo registo e não um segundo. A leitura está sujeita a webhooks:read, pelo que qualquer pessoa a construir uma integração pode ver os endpoints e o seu histórico de entregas (qual disparou, o que o recetor respondeu, quanto tempo demorou) sem ser a proprietária. Registar, editar, testar, rodar e eliminar exigem webhooks:write E a propriedade da caixa de correio, nas duas superfícies, e essa segunda metade é deliberada: um endpoint não tem eixo de endereço, pelo que recebe todos os endereços que o espaço de trabalho detém, com assuntos e destinatários incluídos, e a ausência de permissão significa “pode receber tudo isso”. Uma função que constrói integrações e não lê o correio conduz isto com uma chave do espaço de trabalho.