Eventos e webhooks
Conectando webhooks
Especifique o endereço para receber webhooks nas configurações de integração. Receberá notificações sobre novas cartas, status das caixas de correio e resultados das operações.
Nas configurações de integração, defina um segredo de webhook separado e habilite a entrega. Este segredo é usado para verificar assinaturas de notificação; mail API-key não é adequado para isso.
Formato de notificação
A notificação vem HTTP POST- solicitação com Content-Type: application/json. O campo event contém o tipo de evento, timestamp — hora da notificação, data — dados do evento. A composição de data depende do evento.
O identificador data.event_id permite reconhecer a reentrega. Armazene-o junto com seu ID de integração e processe um evento apenas uma vez.
{ "event": "mail.message.received", "timestamp": "2026-11-01T12:00:00Z", "data": { "event_id": "00000000-0000-4000-8000-000000000001", "created_at": "2026-11-01T12:00:00Z", "mailbox_id": 42, "folder": "INBOX", "uidvalidity": 123456, "uid": 120 }}Verificação e confirmação
O cabeçalho X-Webhook-Signature contém HMAC-SHA256 em notação hexadecimal minúscula. Calcule a assinatura dos bytes originais do corpo da solicitação e do segredo do webhook. Verifique a assinatura antes de processar os dados; re-serializar JSON alterará os bytes que estão sendo assinados.
Após verificar a assinatura e salvar o evento, retorne HTTP 200 ou 201. As respostas 202 e 204 não acusam recebimento. Responda em 10 segundos; Execute um processamento demorado após salvar o evento.
As notificações podem chegar repetidamente e fora de ordem. Antes de alterar o status da assinatura, verifique seus detalhes atuais. O histórico de entrega está disponível nas configurações de integração.
Que eventos ocorrem
mailbox.created- A caixa está criada e pronta para uso.
mailbox.expiring- O fim do período de pagamento da caixa está se aproximando.
mailbox.renewed- O período de pagamento da caixa foi estendido.
mailbox.suspended- O acesso à caixa postal está suspenso: a leitura e o envio ficam indisponíveis.
mailbox.resumed- O acesso à caixa de correio foi restaurado.
mailbox.deleting_soon- Falta uma hora para que a caixa não paga seja excluída.
mailbox.deleted- A caixa foi excluída.
mailbox.account_changed- A caixa de correio está vinculada a outra conta de correio.
mail.message.received- Uma nova carta recebida apareceu na caixa de correio.
mail.operation.succeeded- A operação foi concluída com sucesso. Para o envio, isso significa a aceitação da carta pelo servidor de correio, em vez da entrega na caixa de entrada do destinatário.
mail.operation.failed- A operação falhou.
mail.operation.uncertain- O resultado do envio é desconhecido. Verifique a condição antes de reenviar.
Lembretes de pagamento: 14, 7, 3, 2, 1 dia e uma hora antes do vencimento. A renovação cancela lembretes desatualizados que ainda não foram enviados.