> ## Documentation Index
> Fetch the complete documentation index at: https://docs-hub-campaign.convertt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Integração com Webhooks

> Guia completo para integrar webhooks de status

Receba notificações em tempo real sobre o status de entrega das mensagens.

## Fluxo Completo

```mermaid theme={null}
sequenceDiagram
    participant App as Sua Aplicação
    participant API as Convertt API
    participant Op as Cliente

    App->>API: POST /external/campaigns/dispatch
    API-->>App: 202 Accepted

    API->>Op: Envia mensagem RCS
    Op-->>API: delivered
    API->>App: POST /seu-webhook (delivered)

    Op-->>API: read
    API->>App: POST /seu-webhook (read)

    Op-->>API: clicked
    API->>App: POST /seu-webhook (clicked)
```

## Implementação Recomendada

### 1. Crie um endpoint idempotente

```javascript theme={null}
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);
});
```

### 2. Configure no Dashboard

Vá em [**Configurações**](https://hub-campaign.convertt.ai/settings) > **Webhook de Status** e configure a URL do seu endpoint.

### 3. Atualize seu banco de dados

```javascript theme={null}
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  |

<Tip>
  Use `api_only` se você só precisa receber status de campanhas disparadas programaticamente, evitando ruído de campanhas manuais.
</Tip>