Webhooks
Avisos em tempo real para o seu sistema: endpoints, eventos e entregas.
Para que serve
Um webhook avisa o seu sistema, por uma requisição HTTPS assinada, sempre que algo acontece na Postal: um e-mail entregue, um bounce, uma reclamação, um e-mail recebido, um contato novo. É o jeito de reagir em tempo real em vez de consultar a API.
Quando usar: Para atualizar o seu banco de dados com o resultado dos envios, desativar endereços que deram bounce, abrir um chamado quando chega um e-mail e alertar a equipe quando os envios são pausados.
#Lista de webhooks
Onde fica: Desenvolvedores › Webhooks. Endereço: app.postal.so/webhooks.
| Campo | O que faz |
|---|---|
| Adicionar webhook | Abre o cadastro: a URL do endpoint e os Eventos. |
| URL do endpoint | Precisa ser HTTPS e responder 2xx em até 15 segundos. A Postal envia um POST assinado a cada evento escolhido. |
| Eventos | Marque os que quiser receber (veja Eventos). Marcar todos / Desmarcar todos valem para tudo, e há um par igual em cada grupo. O contador diz N de M selecionados. |
| Coluna | O que mostra |
|---|---|
| Endpoint | A URL (link para o detalhe). |
| Eventos | Quantos eventos o webhook assina. |
| Status | Ativo; Pausado (por alguém do time); ou Desativado por falhas (a Postal desativou depois de 5 dias seguidos sem nenhuma entrega com sucesso). |
| Criado em | A data de criação. |
Veja também: Webhooks (guia) · Webhooks (API).
#Eventos e detalhe do webhook
Eventos que dá para assinar
| Grupo | Eventos |
|---|---|
| E-mails | email.sent (Enviado), email.delivered (Entregue), email.delivery_delayed (Entrega atrasada), email.bounced (Bounce), email.complained (Marcado como spam), email.opened (Aberto), email.clicked (Link clicado), email.replied (Respondido), email.failed (Falhou), email.scheduled (Agendado), email.suppressed (Suprimido) e email.received (Recebido, nas inboxes). |
| Domínios | domain.created, domain.updated e domain.deleted. |
| Supressões | suppression.added (Adicionada) e suppression.removed (Removida). |
| Contatos | contact.created, contact.updated, contact.deleted, contact.segment_entered (Entrou em segmento dinâmico) e contact.segment_exited (Saiu de segmento dinâmico). |
| Formulários | form.submitted (Inscrição recebida). |
| Campanhas | broadcast.sent (Envio concluído). |
| Inbox | inbox.thread.created, inbox.thread.updated, inbox.thread.deleted e inbox.draft.created (Rascunho da IA criado). |
| Envios | sending.paused (Envios pausados) e sending.resumed (Envios retomados), para alertar a equipe na hora. |
O formato do corpo de cada evento está em Webhooks › Payload.
Detalhe de um webhook
Clicar num webhook abre a página dele. No cabeçalho:
| Botão | O que faz |
|---|---|
| Enviar evento de teste | Dispara um evento webhook.test para o endpoint (Evento de teste enviado). Ele aparece nas entregas com o selo Teste. |
| Reativar | Só em webhook Desativado por falhas: volta a enviar. Antes, confira se o endpoint está no ar e responde 2xx. |
| Pausar / Ativar | Interrompe e retoma os envios sem apagar nada. |
| Editar | Muda a URL e os eventos. |
| Remover webhook | O ícone da lixeira. O endpoint deixa de receber eventos e o histórico de entregas é apagado. |
| Parte | O que é |
|---|---|
| Avisos | Em um webhook ativo com entregas falhando, As entregas falham desde ...: se nenhuma der certo em 5 dias, o endpoint é desativado e os donos e admins do time recebem um e-mail. Depois de desativado, Desativamos este endpoint em .... |
| Segredo de assinatura | O segredo whsec_... para validar os cabeçalhos webhook-signature (ou svix-signature) das requisições. Os botões Mostrar segredo/Ocultar segredo e Copiar segredo. Gerar novo troca o segredo: o atual deixa de valer imediatamente, então atualize o seu sistema logo em seguida. |
| Eventos assinados | A lista dos eventos que esse endpoint recebe. |
| Ignorar mudanças de contato vindas de | Proteção contra loops: eventos de contato cuja mudança veio de uma origem listada (por exemplo, o próprio sistema que recebe este webhook e também escreve na Postal) não são enviados. |
| Entregas | O histórico dos eventos enviados, por 30 dias. |
Entregas
| Coluna | O que mostra |
|---|---|
| Evento | O tipo do evento. |
| Status | Pendente, Tentando de novo (com próxima ... mostrando quando), Entregue ou Falhou. |
| Tentativas | Quantas vezes a Postal tentou. |
| Criado em | Quando o evento foi gerado. |
| Reenviar | Dispara de novo aquele evento. |
Clicar numa entrega abre as tentativas: o código HTTP que o seu endpoint devolveu (ou Sem resposta), a hora, a duração em milissegundos e o corpo da resposta ou o erro. Respostas fora de 2xx são reenviadas automaticamente por cerca de 27 horas (8 tentativas), sempre com o mesmo webhook-id, para o seu sistema poder tratar repetições.
Dica
Confira a assinatura de cada requisição e responda 2xx rápido: faça o trabalho pesado depois, numa fila. Veja o passo a passo em Assinatura.
Veja também: Eventos (guia) · Assinatura · Tentativas · Reenviar (API).