Skip to main content
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

curl -X POST https://apis.vectalk.com.br/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

{
  "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

{
  "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

StatusDescrição
sentMensagem enviada ao servidor WhatsApp
deliveredEntregue no dispositivo do destinatário
readLida pelo destinatário
failedFalha no envio

​
Tipos de mensagem recebida

typeConteú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.