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

# Webhooks

> Receba eventos do WhatsApp em tempo real

Webhooks são URLs da sua aplicação que o Hub chama automaticamente quando eventos chegam da Meta (mensagens recebidas, status de entrega, etc.).

## Como funciona

```
Meta  →  Hub  →  Suas URLs registradas
          ↓
    (distribui para todos
     os webhooks ativos
     da instância)
```

Você pode registrar **múltiplas URLs** por instância. Todas recebem o mesmo evento.

## Registrando um webhook

```bash theme={null}
curl -X POST https://apis.vectalk.com.br/api/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "YOUR_INSTANCE_ID",
    "url": "https://meuapp.com/whatsapp/events",
    "name": "Produção"
  }'
```

## Formato dos eventos

Seu endpoint receberá um `POST` com o mesmo payload que a Meta envia ao Hub:

### Mensagem de texto recebida

```json theme={null}
{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WABA_ID",
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": "5511999999999",
          "phone_number_id": "PHONE_NUMBER_ID"
        },
        "contacts": [{
          "profile": { "name": "João Silva" },
          "wa_id": "5511888888888"
        }],
        "messages": [{
          "from": "5511888888888",
          "id": "wamid.HBgLNTUx...",
          "timestamp": "1700000000",
          "type": "text",
          "text": { "body": "Olá, quero mais informações" }
        }]
      }
    }]
  }]
}
```

### Status de entrega

```json theme={null}
{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WABA_ID",
    "changes": [{
      "field": "messages",
      "value": {
        "statuses": [{
          "id": "wamid.HBgLNTUx...",
          "status": "delivered",
          "timestamp": "1700000010",
          "recipient_id": "5511888888888"
        }]
      }
    }]
  }]
}
```

## Status possíveis

| Status      | Descrição                               |
| ----------- | --------------------------------------- |
| `sent`      | Mensagem enviada ao servidor WhatsApp   |
| `delivered` | Entregue no dispositivo do destinatário |
| `read`      | Lida pelo destinatário                  |
| `failed`    | Falha no envio                          |

## Tipos de mensagem recebida

| `type`        | Conteúdo                                                                       |
| ------------- | ------------------------------------------------------------------------------ |
| `text`        | `.text.body`                                                                   |
| `image`       | `.image.id`, `.image.caption`                                                  |
| `document`    | `.document.id`, `.document.filename`                                           |
| `audio`       | `.audio.id`                                                                    |
| `video`       | `.video.id`                                                                    |
| `sticker`     | `.sticker.id`                                                                  |
| `location`    | `.location.latitude`, `.location.longitude`                                    |
| `contacts`    | `.contacts[]`                                                                  |
| `interactive` | `.interactive.type` + `.interactive.button_reply` ou `.interactive.list_reply` |
| `reaction`    | `.reaction.message_id`, `.reaction.emoji`                                      |
| `order`       | `.order.catalog_id`, `.order.product_items[]`                                  |

## Resposta esperada

Seu endpoint deve retornar HTTP `200` em menos de **20 segundos**. Se não retornar, o Hub tentará reenviar.