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.
Quando usar cada um
Seção intitulada “Quando usar cada um”| 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.
A receita
Seção intitulada “A receita”// 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 });}Uma diferença, e ela é de propósito
Seção intitulada “Uma diferença, e ela é de propósito”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.
