Pular para o conteúdo

Webhook e API são o mesmo objeto

Cada item que a consulta devolve é idêntico ao que o webhook manda em param.details (formato v1) ou em data (formato v2).

Isso não é coincidência de desenho: os dois saem do mesmo objeto, do nosso lado. Quem já trata o webhook já sabe ler a resposta da consulta, e vice-versa — você escreve o parser uma vez.

Os campos de message, delivery e engagement estão descritos em O bloco param.details.

Webhook você quer saber no momento em que acontece
Consulta você quer o estado agora, ou o motivo de uma falha específica

O webhook avisa; a consulta responde o detalhe. O caminho mais comum de integração usa os dois.

// 1. O seu endpoint recebe o evento e responde 2xx IMEDIATAMENTE.
app.post('/webhook/iporto', (req, res) => {
res.sendStatus(200);
// 2. O processamento acontece depois, fora do ciclo da resposta.
fila.enfileirar(req.body);
});
// 3. No processamento, o código de rastreio liga o evento à sua mensagem.
async function processar(evento) {
// v1: param.message_tracking_code · v2: data.message.tracking_code
const codigo = evento.param?.message_tracking_code ?? evento.data?.message?.tracking_code;
const pedido = await meuBanco.acharPorCodigo(codigo);
// 4. O detalhe já vem NO evento — `param.details` (v1) ou `data` (v2).
// A consulta só é necessária quando você quer o motivo do bounce.
const detalhe = evento.param?.details ?? evento.data;
await pedido.atualizar({ status: detalhe.delivery.status });
}

Na resposta da consulta, o bloco event vem nulo.

Uma consulta não é um evento. Preencher aquele bloco daria a você um identificador que não corresponde a nenhum webhook recebido, e um horário que é o da sua consulta — dois dados que parecem úteis e levam a conciliação errada.

A chave continua existindo para o formato ser o mesmo nos dois lugares. Se você quer eventos, use o webhook.