Introdução/Webhooks

Webhooks

Receba notificações em tempo real sobre eventos do WhatsApp

Visão geral

Webhooks permitem que sua aplicação receba notificações em tempo real sobre eventos que acontecem no WhatsApp, como mensagens recebidas, status de entrega e atualizações de conexão.

Como funciona

Quando um evento ocorre, a TurboZap API envia uma requisição HTTP POST para a URL que você configurou, com todos os dados do evento no corpo da requisição.

Configurar webhook

Para configurar um webhook para sua instância:

POST/webhook/:instance/configureConfigurar webhook

Requisição

curl --request POST \
  --url http://localhost:8080/webhook/minha-instancia/configure \
  --header 'X-API-Key: sua-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://seu-servidor.com/webhook",
    "events": ["message.received", "message.sent", "connection.update"],
    "enabled": true
  }'

Resposta

{
  "success": true,
  "data": {
    "webhook": {
      "id": "wh_123456",
      "url": "https://seu-servidor.com/webhook",
      "events": ["message.received", "message.sent", "connection.update"],
      "enabled": true,
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  }
}

Eventos disponíveis

Você pode se inscrever nos seguintes eventos:

Evento	Descrição
`message.received`	Nova mensagem recebida
`message.sent`	Mensagem enviada com sucesso
`message.delivery`	Status de entrega atualizado
`message.read`	Mensagem foi lida
`connection.update`	Status da conexão alterado
`qrcode.update`	Novo QR Code gerado
`group.update`	Informações do grupo atualizadas
`group.participants`	Participantes adicionados/removidos
`presence.update`	Status de presença atualizado

Estrutura do payload

Cada webhook enviado segue esta estrutura:

Exemplo: message.received

{
  "event": "message.received",
  "instance": "minha-instancia",
  "timestamp": "2024-01-15T10:35:00.000Z",
  "data": {
    "message_id": "3EB0A1B2C3D4E5F6",
    "from": "5511999999999@s.whatsapp.net",
    "to": "5511888888888@s.whatsapp.net",
    "type": "text",
    "content": {
      "text": "Olá, tudo bem?"
    },
    "timestamp": "2024-01-15T10:35:00.000Z",
    "is_group": false,
    "push_name": "João Silva"
  }
}

Exemplo: connection.update

{
  "event": "connection.update",
  "instance": "minha-instancia",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "status": "connected",
    "phone_number": "5511888888888",
    "profile_name": "Minha Empresa"
  }
}

Segurança

Use HTTPS

Sempre use URLs HTTPS para seus webhooks em produção.

Valide a origem

Verifique o IP de origem ou use um token secreto para validar que a requisição veio da TurboZap API.

Responda rápido

Retorne um status 200 rapidamente. Processe os dados de forma assíncrona se necessário.

Timeout

A TurboZap API aguarda no máximo 10 segundos por uma resposta. Se o timeout for atingido, a entrega é considerada falha e será tentada novamente.