Receba notificações em tempo real sobre o status de entrega das mensagens.
Fluxo Completo
Implementação Recomendada
1. Crie um endpoint idempotente
const processedEvents = new Set(); // Use um cache persistente em produção
app.post('/webhook/rcs', express.json(), (req, res) => {
// Responda 200 imediatamente
res.status(200).send('OK');
const { data } = req.body;
const eventKey = `${data.dispatchId}:${data.status}`;
// Idempotência
if (processedEvents.has(eventKey)) return;
processedEvents.add(eventKey);
// Processe de forma assíncrona
processEvent(data).catch(console.error);
});
3. Atualize seu banco de dados
async function processEvent(data) {
const { uid, status, phone, failureReason } = data;
await db.query(
`UPDATE mensagens
SET status = $1, updated_at = NOW(), failure_reason = $2
WHERE external_id = $3`,
[status, failureReason, uid]
);
// Notifique seus sistemas internos
if (status === 'failed') {
await notifyFailure(uid, phone, failureReason);
}
}
Tratando Falhas
| Cenário | Ação Recomendada |
|---|
| Webhook retorna 5xx | Retry automático (até 5 tentativas) |
| Webhook timeout (>10s) | Retry automático |
| Webhook retorna 4xx | Não será retentado — verifique seus logs |
| Mensagem duplicada | Ignore via idempotência (dispatchId + status) |
Escopo de Webhooks
Configure o escopo para controlar quais campanhas geram webhooks:
| Escopo | Descrição |
|---|
all | Webhooks para todas as campanhas (dashboard + API) |
api_only | Webhooks apenas para campanhas disparadas via API |
Use api_only se você só precisa receber status de campanhas disparadas programaticamente, evitando ruído de campanhas manuais.
