Os eventos de webhook e seus corpos

Cada evento marcado na tela de configuração 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.

Eventos que aparecem na tela e ainda não são enviados

Algumas caixas existem na tela e não têm origem hoje. Marcá-las não causa erro e não gera envio — estão listadas aqui de propósito, porque é melhor você saber que não vai receber do que esperar por um evento que não vem.

Evento	Canal
msg_engagement_unsubscribe	SMS
msg_engagement_compliance_spam	SMS
msg_engagement_answer	SMS
msg_deliverability_yes_queue	SMS

No canal Prospecção, a configuração existe e nenhum evento é gerado por envio real.

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.

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"
        ],
        "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.

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",
        "id": "<identificador do registro>"
    }
}

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

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.

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.

O formato não muda

O formato descrito aqui é estável. Se publicarmos um formato novo, ele será opcional e escolhido por endereço: nada do que está nesta página deixa de valer para quem já integrou.