> ## Documentation Index
> Fetch the complete documentation index at: https://developers.datafyapi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Introdução

> Como a Datafy entrega os webhooks da Meta para a sua aplicação.

Webhook é a forma de a sua aplicação ser avisada do que acontece no número: uma mensagem recebida, a confirmação de leitura, a aprovação de um template ou uma mudança na qualidade da conta. Em vez de consultar a API de tempos em tempos, a Datafy envia um `POST` para a sua URL assim que o evento chega da Meta.

O **payload é idêntico ao que a Meta envia**, sem nenhuma alteração.

## Cadastrar uma URL

No [painel da Datafy](https://app.datafyapi.com.br), abra a aba **Webhooks** do número e cadastre a URL de entrega. A URL precisa usar **HTTPS**.

As mesmas URLs também podem ser cadastradas e alteradas pela API, em [Criar webhook](https://developers.datafyapi.com.br/api-reference/administracao/criar-webhook.md), o que é o caminho de quem gerencia os canais pelo próprio sistema.

Ao cadastrar, marque quais eventos aquela URL deve receber. Cada URL recebe apenas os eventos marcados, e é possível cadastrar mais de uma URL para o mesmo número, cada uma com a sua seleção — por exemplo, uma URL para mensagens e outra para eventos administrativos.

## Estrutura do payload

Todos os eventos chegam no mesmo envelope. O que muda é o `field`, que identifica o evento, e o `value`, que carrega o conteúdo:

```json theme={null}
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "1234567890123456",
      "changes": [
        {
          "value": { },
          "field": "messages"
        }
      ]
    }
  ]
}
```

| Campo | Descrição |
| - | - |
| `object` | Sempre `whatsapp_business_account` |
| `entry[].id` | ID da conta do WhatsApp Business (`waba_id`) |
| `changes[].field` | Nome do evento, como `messages` ou `message_template_status_update` |
| `changes[].value` | Conteúdo do evento, com formato próprio para cada `field` |

> [!NOTE]
>
> Um mesmo `POST` pode trazer mais de um item em `entry` e em `changes`. Percorra as duas listas em vez de ler apenas o primeiro item.

## Headers da entrega

| Header | Descrição |
| - | - |
| `x-datafy-delivery-id` | Identificador único da entrega (UUID). Use como chave de idempotência. |
| `x-datafy-timestamp` | Unix timestamp, em segundos, de quando a entrega foi assinada. |
| `x-datafy-signature-256` | Assinatura HMAC-SHA256, no formato `sha256=<hex>`. |

Os três headers acompanham todas as entregas. A verificação está em [Assinatura](https://developers.datafyapi.com.br/api-reference/whatsapp/webhooks/validar-assinatura.md).

## Resposta e tempo limite

Sua URL deve responder **`200` em até 20 segundos**. Depois disso, a entrega é contabilizada como falha.

> [!TIP]
>
> Responda `200` imediatamente e processe o evento em segundo plano. Processamento síncrono longo é a causa mais comum de estouro do tempo limite.

## Reentrega automática

Quando uma entrega falha — resposta diferente de `200` ou tempo limite estourado —, a Datafy tenta de novo automaticamente. O comportamento depende do evento:

* **Eventos em tempo real** (mensagens, status, templates, eventos de conta): a entrega é repetida três vezes, em `2s`, `10s` e `30s`. Persistindo a falha, aquele evento é descartado.
* **Sincronizações de coexistência** (`history` e `smb_app_state_sync`): por entregarem dados únicos e não repetíveis, a reentrega dura mais e com intervalos maiores — `10s`, `1min`, `5min` e `30min`. Detalhes em [Histórico de conversas](https://developers.datafyapi.com.br/api-reference/whatsapp/webhooks/eventos/historico.md) e [Contatos sincronizados](https://developers.datafyapi.com.br/api-reference/whatsapp/webhooks/eventos/contatos-sincronizados.md).

O `x-datafy-delivery-id` **é o mesmo** em todas as tentativas da mesma entrega. Use-o como chave de idempotência: se uma tentativa chegar depois de a anterior já ter sido processada, descarte a repetida pelo `delivery-id`.

> [!NOTE]
>
> Cada tentativa é assinada na hora, com um `x-datafy-timestamp` novo. Valide a assinatura sempre contra o timestamp recebido no cabeçalho daquela entrega, não contra um valor guardado.

Os eventos estão detalhados nas páginas desta seção, começando por [Mensagens recebidas](https://developers.datafyapi.com.br/api-reference/whatsapp/webhooks/eventos/mensagens.md). A lista completa de eventos da plataforma está na [documentação de webhooks da Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.