Os eventos de webhook e seus corpos

Cada evento marcado na tela do endpoint gera um POST para o seu endereço. Esta página lista os eventos de cada canal e o corpo que chega em cada um.

O nome do evento vem no campo event do corpo e também no cabeçalho X-iPORTO-Event.

Canal e-mail

Evento	Como aparece na tela	Quando acontece
msg_deliverability_yes_queue	Mensagem recebida	a mensagem foi aceita — somente no envio pela API; o envio por SMTP não gera este evento
msg_deliverability_yes_delivery	Mensagem entregue ao destinatário	a mensagem foi entregue ao servidor do destinatário
msg_deliverability_not_delivery_soft_bounce	Falha temporária na entrega	recusa temporária do provedor; a entrega ainda pode acontecer
msg_deliverability_not_delivery_hard_bounce	Falha permanente na entrega	recusa definitiva, normalmente endereço inexistente
msg_deliverability_not_accepted	Mensagem rejeitada (total ou parcial)	a mensagem foi descartada por filtro do destino
msg_engagement_open	E-mail foi aberto pelo destinatário	o destinatário abriu a mensagem
msg_engagement_click	Link do e-mail foi clicado	o destinatário clicou em um link
msg_engagement_compliance_spam	E-mail foi marcado como spam	o destinatário marcou a mensagem como spam e o provedor nos avisou

A reclamação de spam depende do provedor

msg_engagement_compliance_spam chega pelo canal de retorno dos provedores que o oferecem — não é todo provedor, e não é toda reclamação. No mesmo momento em que o aviso chega, o endereço do destinatário entra na lista de supressão do domínio, e o SMTP para de enviar para ele. O evento existe para você refletir isso no seu cadastro.

Entregue não é “na caixa de entrada”

msg_deliverability_yes_delivery significa que o servidor do destinatário aceitou a mensagem. O que acontece depois disso — caixa de entrada, promoções, spam — é decisão do provedor, e não há evento que a reporte.

Canal SMS

Evento	Quando acontece
msg_deliverability_yes_delivery	o SMS foi aceito pela operadora
msg_deliverability_not_accepted	o SMS não foi aceito

No SMS, yes_delivery é “aceito pela operadora”

Não é a confirmação de entrega no aparelho. Se o seu relatório depende de entrega confirmada no aparelho, este não é o campo.

Todo evento da tela é enviado

Não há, hoje, nenhuma caixa que você possa marcar e que não gere envio. Tudo o que a tela oferece chega ao seu endereço.

Se você integrou o SMS antes de outubro de 2026, a tela antiga oferecia quatro caixas que nunca enviaram nada — resposta, descadastro, reclamação de spam e o aceite pela operadora. Elas saíram. Se o seu sistema esperava por algum desses eventos, ele nunca os recebeu, e não é defeito da sua integração.

Entrega confirmada no aparelho ainda não tem evento

No SMS, msg_deliverability_yes_delivery é “aceito pela operadora”. A confirmação de entrega no aparelho existe do nosso lado e ainda não tem evento de webhook — quando tiver, ele aparece na tabela acima, e esta nota sai.

A Prospecção não tem eventos próprios: as mensagens dela saem por e-mail e geram os eventos do canal e-mail, listados acima. Para separá-las das transacionais, olhe param.tags — elas chegam com application_prospect_email, prospect e approach.

Os corpos

São três formas, pela origem do evento. Os campos não listados aqui podem aparecer e não devem ser usados: o que esta página descreve é o que tem contrato.

Em todas as formas, param traz também o details — o registro inteiro da mensagem, com assunto, remetente, destinatários, desfecho da entrega e o motivo da falha. Ele está descrito em O bloco param.details e aparece inteiro nos dois primeiros exemplos abaixo.

Mensagem processada — entrega, falha e descarte

{
    "email": [
        "[email protected]"
    ],
    "event": "msg_deliverability_yes_delivery",
    "about": {
        "status": "msg:yes:finished",
        "sum_hard_bounce": 0,
        "sum_soft_bounce": 0,
        "sum_discarded": 0
    },
    "param": {
        "message_id": "1s9KpQ-0004Zx-2H",
        "message_id_relay": "1s9KpR-0007Bd-9K",
        "message_tracking_code": "<o seu código de rastreio>",
        "tags": [
            "transacional",
            "pedido-1234"
        ],
        "details": {
            "object": "message",
            "event": {
                "type": "email.delivered",
                "occurred_at": "2026-10-15T09:12:04-03:00",
                "emitted_at": "2026-10-15T09:14:31-03:00",
                "id": "01M4YQV7RC6VKAVJM5E6B4TCY8"
            },
            "channel": "email",
            "message": {
                "tracking_code": "<o seu código de rastreio>",
                "message_id": "1s9KpQ-0004Zx-2H",
                "message_id_relay": "1s9KpR-0007Bd-9K",
                "subject": "Seu pedido 1234",
                "body": null,
                "from": "[email protected]",
                "from_visible": "Loja <[email protected]>",
                "to": "[email protected]",
                "recipients": [
                    "[email protected]"
                ],
                "tags": [
                    "transacional",
                    "pedido-1234"
                ],
                "smtp_domain_id": 4180,
                "smtp_account_id": 9271,
                "plan_type": "smtp",
                "sent_at": "2026-10-15T09:11:58-03:00",
                "id": "<identificador do registro>"
            },
            "delivery": {
                "status": "msg:yes:finished",
                "hard_bounce": 0,
                "soft_bounce": 0,
                "discarded": 0,
                "trap": 0,
                "bounce": null
            },
            "engagement": null
        },
        "id": "<identificador do registro>"
    }
}

about.status e os contadores dizem o desfecho: sum_hard_bounce em 1 na falha permanente, sum_soft_bounce na temporária, sum_discarded no descarte por filtro.

Aceite pela API

{
    "email": "[email protected]",
    "event": "msg_deliverability_yes_queue",
    "about": {
        "status": "msg:yes:queue"
    },
    "param": {
        "message_tracking_code": "<o seu código de rastreio>",
        "http_request_params": {
            "address_to": "[email protected]",
            "subject": "Seu pedido 1234",
            "html_body": "<html>corpo</html>"
        },
        "id": "<identificador do registro>"
    }
}

Este corpo repete a sua requisição de envio

param.http_request_params traz a requisição que você fez, incluindo o corpo da mensagem. Se o seu endpoint grava o que recebe, ele passa a guardar o conteúdo dos seus e-mails. Vale decidir isso de propósito, não por acidente.

O param.details vem aqui também — foi omitido acima para não repetir o bloco. Neste evento a mensagem acabou de ser aceita e ainda não saiu, então details.message.message_id, subject, from, tags e sent_at vêm vazios: o que você enviou está em param.http_request_params, no mesmo corpo.

Engajamento — abertura e clique

{
    "email": null,
    "event": "msg_engagement_click",
    "about": {
        "status": "msg:yes:finished",
        "sum_hard_bounce": null,
        "sum_soft_bounce": null,
        "sum_discarded": null
    },
    "param": {
        "message_id": "1s9KpQ-0004Zx-2H",
        "message_id_relay": "1s9KpR-0007Bd-9K",
        "message_tracking_code": "<o seu código de rastreio>",
        "tags": [
            "transacional",
            "pedido-1234"
        ],
        "link": "https://cliente.com.br/pedido/1234",
        "details": {
            "object": "message",
            "event": {
                "type": "email.clicked",
                "occurred_at": "2026-10-15T14:02:17-03:00",
                "emitted_at": "2026-10-15T14:02:17-03:00",
                "id": "01M4Z8F3QW1ABCDEF2GHJK3MNP"
            },
            "channel": "email",
            "message": {
                "tracking_code": "<o seu código de rastreio>",
                "message_id": "1s9KpQ-0004Zx-2H",
                "message_id_relay": "1s9KpR-0007Bd-9K",
                "subject": "Seu pedido 1234",
                "body": null,
                "from": "[email protected]",
                "from_visible": "Loja <[email protected]>",
                "to": "[email protected]",
                "recipients": [
                    "[email protected]"
                ],
                "tags": [
                    "transacional",
                    "pedido-1234"
                ],
                "smtp_domain_id": 4180,
                "smtp_account_id": 9271,
                "plan_type": "smtp",
                "sent_at": "2026-10-15T09:11:58-03:00",
                "id": "<identificador do registro>"
            },
            "delivery": {
                "status": "msg:yes:finished",
                "hard_bounce": 0,
                "soft_bounce": 0,
                "discarded": 0,
                "trap": 0,
                "bounce": null
            },
            "engagement": {
                "link": "https://cliente.com.br/pedido/1234",
                "ip": "203.0.113.7",
                "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
                "device": "desktop",
                "platform": "macOS",
                "referer": null
            }
        },
        "id": "<identificador do registro>"
    }
}

No clique, param.link traz o endereço clicado. Na abertura, o campo não existe.

É só aqui que details.engagement deixa de ser nulo: ele descreve o acesso do destinatário, e nos eventos de entrega ninguém acessou nada.

email vem nulo no engajamento

E os contadores de about também. É assim desde a primeira versão e não vai mudar: o seu código não deve depender da presença desses campos — use message_tracking_code para resolver a mensagem.

Canal SMS

{
    "phone": "5511999998888",
    "event": "msg_deliverability_yes_delivery",
    "about": "",
    "param": {
        "id": "<identificador do registro>"
    }
}

No SMS, about é uma string vazia

Não um objeto, como no e-mail. Quem escreve um tratamento único para os dois canais precisa saber disso.

O param.details vem aqui também, com channel: "sms". O que o canal não tem fica nulo: subject, message_id_relay, tags e o bloco engagement. Em from e to vão os telefones.

O bloco param.details

É o registro inteiro da mensagem, o mesmo que você vê no painel — assunto, remetente, destinatários, desfecho da entrega e, quando houve falha, a resposta do servidor de destino. Ele existe para você não precisar consultar a API depois de cada evento.

Está em todo evento, nos dois canais, nas três formas de corpo.

É acréscimo, e nada mais

Nenhuma chave anterior mudou de nome, de valor ou de posição, e o topo do corpo segue com as mesmas quatro chaves. Quem já integrou não precisa fazer nada: quem lê param.message_id hoje continua lendo.

Bloco	O que traz
object	sempre "message"
event	o fato: tipo, quando ocorreu, quando saiu, e o identificador
channel	email ou sms
message	a mensagem: assunto, remetente, destinatários, etiquetas
delivery	o desfecho da entrega, com o motivo da falha
engagement	o acesso do destinatário — nulo fora de abertura e clique

event

Campo	O que é
type	o nome do evento no formato novo — email.delivered, email.clicked, sms.accepted
occurred_at	quando o fato aconteceu
emitted_at	quando nós o emitimos
id	identificador do fato; é o mesmo valor do cabeçalho X-iPORTO-Event-Id

Os dois instantes respondem “por que o webhook demorou”

occurred_at é quando o provedor respondeu; emitted_at é quando o evento saiu daqui. A diferença entre os dois é o nosso tempo de processamento, e ela é visível — em vez de você precisar inferi-la do horário em que o POST chegou.

event.type e o campo event do corpo são nomenclaturas diferentes

event.type usa os nomes do formato novo (email.delivered); o campo event, no topo do corpo, usa os desta versão (msg_deliverability_yes_delivery). Os dois descrevem o mesmo fato. Para decidir o que fazer, use o event do topo — é ele que tem contrato aqui.

message

Campo	O que é
tracking_code	o localizador da mensagem — o mesmo de param.message_tracking_code
message_id	identificador do servidor de envio
message_id_relay	identificador do relay
subject	o assunto
body	o texto da mensagem — só em SMS recebido; em e-mail é sempre nulo
from	o endereço remetente
from_visible	o remetente como o destinatário o vê, com nome
to	o destinatário principal
recipients	todos os destinatários, como lista
tags	as suas etiquetas, as mesmas de param.tags
smtp_domain_id	o domínio de envio
smtp_account_id	a conta de autenticação usada
plan_type	de onde a mensagem saiu — smtp, email_marketing, marketing ou prospect
sent_at	quando a mensagem saiu
id	identificador do registro de histórico; o mesmo de param.id

delivery

Campo	O que é
status	o status final, na forma msg:yes:finished com sufixo quando houve falha
hard_bounce	quantos destinatários deram falha permanente
soft_bounce	quantos deram falha temporária
discarded	quantos o destino descartou ou filtrou
trap	quantos caíram em armadilha de spam
bounce	o motivo, quando houve

delivery.bounce é o campo que mais muda o seu atendimento: ele diz qual foi a resposta do servidor de destino, e não só que houve uma falha.

{
    "kind": "hard",
    "code": "550",
    "answer": "550 5.1.1 The email account does not exist",
    "domain": "exemplo.com.br"
}

Campo	O que é
kind	hard, soft, discarded ou trap
code	o código SMTP extraído da resposta
answer	a resposta do servidor de destino, como ela veio
domain	o domínio que respondeu

bounce pode vir nulo mesmo em evento de falha

Ele vem nulo quando não houve falha e também quando o detalhe da mensagem não estava disponível no momento de emitir o evento — o campo é um extra, e não vale uma consulta a mais no caminho de cada evento. Não construa a sua lógica sobre a presença dele: o desfecho está em about e em delivery.

engagement

Só em abertura e clique. Nos outros eventos é null.

Campo	O que é
link	o endereço clicado; nulo na abertura
ip	o IP do acesso
user_agent	o User-Agent recebido
device	o tipo de dispositivo
platform	o sistema operacional
referer	a origem do clique, quando o navegador a informa

Este bloco é dado pessoal do seu destinatário

IP e User-Agent identificam uma pessoa, e quem recebe passa a ser responsável por eles. Se o seu sistema não precisa desses campos, descarte-os na entrada em vez de gravá-los por acidente.

O corpo ficou maior

Com details, um evento sai de cerca de 400 bytes para cerca de 1,5 KB. Se o seu endpoint tem limite de tamanho de corpo, ele precisa de folga. O prazo de resposta continua o mesmo: 15 segundos.

As etiquetas

O campo param.tags traz as etiquetas que você enviou na requisição de envio, no campo tags. Elas viajam com a mensagem e voltam em todo evento dela — é o caminho para carregar a sua própria classificação (campanha, tipo de mensagem, identificador de pedido) sem depender de uma consulta do seu lado.

A iPORTO também acrescenta as suas. Mensagem enviada pela Prospecção chega com application_prospect_email, prospect e approach, e é assim que você separa o que é prospecção do que é transacional sem precisar de outro endereço de webhook.

O formato não muda, e você não fica para trás

Nenhum campo descrito aqui vai desaparecer, mudar de nome ou mudar de posição. É o compromisso desta versão do formato, e ele vale sem prazo: não há data de fim de vida.

Um formato novo, quando houver, será opcional e escolhido por endereço — e você não precisa fazer nada para continuar funcionando.

E o formato atual continua recebendo melhoria de dado:

campo novo dentro de param.details	você recebe, sem mexer em nada
tipo de evento novo	só no formato novo — o atual nomeia os eventos pelos nomes desta página, e um evento novo não tem nome aqui
mudança no significado de um evento que já existe	nunca nesta versão: seria quebrar quem já conta em cima dele

Programe tolerando campo novo

A única coisa que pedimos do seu lado: não recuse o corpo por conter chave que você não conhece. Validação estrita de param já quebraria hoje ao trocar de evento — link só aparece no clique, http_request_params só no aceite pela API —, e é ela que transforma uma melhoria nossa em incidente seu.