Receber eventos por webhook

O webhook avisa o seu sistema, na hora, o que aconteceu com cada mensagem: ela foi aceita, entregue, voltou, foi aberta, teve um link clicado. Em vez de consultar a API de tempo em tempo, o seu sistema recebe um POST a cada evento.

Antes de começar

• Um endereço público do seu sistema para receber os eventos. Endereço de rede interna, localhost ou IP privado não é aceito: o envio sai dos nossos servidores e precisa alcançar o seu.
• Esse endereço precisa responder 2xx em até 15 segundos. Se o seu processamento é demorado, responda primeiro e processe depois.

Passo a passo

O webhook é configurado por serviço, no painel de cada um — e a tela muda de nome:

Serviço	Onde configurar
E-mail (SMTP)	Webhook → Configurações
SMS	Gatilhos
Prospecção	Webhook → Configurações

No painel de e-mail (SMTP) e no de Prospecção:

1. Em URL do Endpoint, informe o endereço que vai receber os eventos.
2. Em Método de Autorização, escolha Nenhuma ou Bearer Token. Escolhendo Bearer Token, informe em Token de Autorização o valor que o seu sistema espera receber no cabeçalho Authorization.
3. Marque os eventos que você quer receber. Ver Os eventos e os corpos.
4. Clique em Salvar Configuração.
5. Em Segredo de assinatura, clique em Gerar novo segredo e copie o valor. É com ele que o seu sistema confere que o envio veio da iPORTO — ver Verificar a assinatura.

O segredo aparece uma única vez

Ele não é exibido em nenhuma leitura posterior. Se você fechar a tela sem copiá-lo, gere outro. O mesmo vale para o token de autorização: depois de salvo, a tela mostra apenas os últimos quatro caracteres.

Ao gerar um segredo novo, o anterior continua válido por 24 horas. Use essa janela para publicar o novo no seu sistema sem recusar os eventos que chegarem no meio.

Mais de um endereço no mesmo canal

A tela de Configurações mostra um endereço: o principal. No painel de e-mail (SMTP), em Webhook → Endpoints, você cadastra até cinco endereços para o canal — por exemplo, um para o ERP e outro para a ferramenta de atendimento. Todos os ativos que assinam o evento recebem o mesmo evento, cada um com o seu próprio X-iPORTO-Delivery.

Nessa tela, cada endereço tem:

Ação	O que faz
Novo endpoint	cadastra outro endereço no canal, com os próprios eventos e a própria autorização
Pausar / Reativar	para de receber sem perder a configuração
Tornar principal	passa a ser o endereço que a tela de Configurações mostra e edita
Gerar segredo	gera o segredo de assinatura daquele endereço — cada um tem o seu
Excluir	remove o endereço

Tornar principal muda a tela de Configurações

As duas telas falam do mesmo canal: promover um endereço aqui é o que a tela de Configurações passa a mostrar e a gravar. Se você usa só um endereço, não precisa desta tela.

Excluir o principal promove outro

Quando o endereço principal é excluído, o mais antigo que sobra assume — ativo antes de pausado — e passa a ser o que a tela de Configurações mostra.

No SMS a tela é mais simples

A tela Gatilhos do painel de SMS tem apenas o endereço e os dois eventos do canal. Autorização e segredo de assinatura não são configuráveis ali.

O que acontece depois

A cada evento, a iPORTO faz uma requisição ao seu endereço:

POST https://seu-sistema.com.br/webhook
Content-Type: application/json

O seu sistema responde 2xx e nada mais é necessário. Qualquer outra resposta, ou nenhuma resposta, é tratada como falha — ver Repetição e falhas.

Os cabeçalhos de cada envio

Cabeçalho	O que é
Content-Type	sempre application/json
User-Agent	identifica o envio como da iPORTO
X-iPORTO-Event	o nome do evento, igual ao campo event do corpo
X-iPORTO-Event-Id	identificador do fato
X-iPORTO-Delivery	identificador desta entrega
X-iPORTO-Attempt	número da tentativa, começando em 1
X-iPORTO-Timestamp	instante do envio, ISO-8601
X-iPORTO-Signature	a assinatura; ver Verificar a assinatura
Authorization	Bearer <token>, quando você configurou um

Os dois identificadores, e para que serve cada um

• X-iPORTO-Event-Id é o fato. Se você cadastrou mais de um endereço no canal, todos recebem o mesmo Event-Id para o mesmo acontecimento — é com ele que você sabe que recebeu o mesmo evento duas vezes, e não dois eventos.
• X-iPORTO-Delivery é esta entrega: o evento mais o endereço de destino. É o valor a guardar para descartar repetição: uma retentativa chega com o mesmo Delivery e com Attempt maior.

Guarde o X-iPORTO-Delivery e ignore o que já processou

Uma entrega pode chegar mais de uma vez. Uma resposta sua que demorou mais de 15 segundos é tratada como falha aqui e será repetida, mesmo que você já a tenha processado.

Casar o evento com a sua mensagem

Todo corpo traz param.message_tracking_code: é o localizador da mensagem, e é o campo para guardar do seu lado.

Se você envia pela API, pode escolher esse valor: mande o cabeçalho X-Request-Id na sua requisição de envio e ele passa a ser o código de rastreio da mensagem — a resposta devolve o mesmo valor no cabeçalho X-Request-Id e no campo data.message_tracking_code.

O código também vai no cabeçalho X-Mailer-Tracking-Code da mensagem enviada.

Esse cabeçalho chega ao destinatário

Como qualquer cabeçalho de e-mail, ele aparece para quem usar “ver código-fonte” na caixa de entrada. Não use nele nada que você não queira mostrar — número de contrato interno, identificador de cliente de terceiro, dado pessoal.

Os campos param.message_id e param.message_id_relay não correspondem ao que a API devolve no envio: são identificadores gerados pelo servidor de envio e pelo relay no momento da transmissão, e só existem a partir dali. Servem para rastreamento junto ao suporte, não como chave de correlação.

Testar

No painel de SMS, a tela Gatilhos tem o botão Enviar um teste, que dispara um evento com corpo real para o seu endereço. Cada clique gera um identificador novo, então você pode clicar quantas vezes quiser.

No e-mail (SMTP) e na Prospecção não há botão de teste: a forma de exercitar a integração é enviar uma mensagem de verdade para um endereço seu e acompanhar os eventos em Webhook → Histórico de Disparos. Lá, no detalhe de cada disparo, o botão Reenviar repete o envio para o endereço configurado hoje — é o caminho para testar uma correção no seu endpoint sem precisar de uma mensagem nova.

Limites

timeout de cada tentativa	15 segundos
tentativas	6, numa janela de aproximadamente 10 h 36
histórico de disparos	7 dias
redirecionamento	não seguimos
endereços por canal	até 5

Se der errado

Sintoma	Causa provável	O que fazer
A tela recusa o endereço informado	Endereço de rede interna, localhost, IP privado ou esquema diferente de http/https	Use um endereço público, alcançável da internet
Nenhum evento chega	Nenhum evento marcado na tela, ou endereço salvo vazio	Confira as caixas de evento e salve de novo; use o botão de enviar evento de teste para confirmar o caminho
Os eventos pararam de chegar, e você recebeu um e-mail de aviso	Dez entregas seguidas sem resposta 2xx desativaram o endereço	Corrija o que impedia a resposta e clique em Reativar endpoint na tela de configuração
O mesmo evento chega mais de uma vez	Sua resposta passou de 15 segundos, ou não foi 2xx	Responda 2xx antes de processar, e descarte repetição pelo X-iPORTO-Delivery
A assinatura não confere	O corpo foi interpretado e serializado de novo antes de assinar, ou só um valor v1 foi lido	Assine o corpo cru e trate v1 como lista — ver Verificar a assinatura
Chega evento de uma mensagem que você não reconhece	O endereço está configurado na conta, e a conta pode ter mais de um sistema enviando	Use param.message_tracking_code para resolver a mensagem, e o X-Request-Id no envio para carimbar o seu próprio identificador