GWhats
    Integrações em Tempo Real

    Webhooks GWhats

    Receba notificações HTTP em tempo real sempre que algo acontecer na plataforma. Ideal para integrar com n8n, Zapier, CRMs e sistemas próprios.

    Tempo real

    Eventos entregues em milissegundos após a ação

    Retentativas

    3 tentativas automáticas em caso de falha

    Seguro

    Valide a origem dos eventos com HMAC

    Visão Geral

    Webhooks são URLs que o GWhats chama automaticamente quando um evento ocorre — uma nova mensagem chega, uma conversa é resolvida, um contato é criado. Em vez de sua aplicação ficar consultando a API repetidamente, o GWhats avisa você na hora.

    Como funciona

    1

    Você registra uma URL em Configurações → Integrações → Webhooks (ou via API)

    2

    Um evento acontece na plataforma (ex: cliente envia uma mensagem)

    3

    O GWhats faz um POST para a sua URL com o payload JSON do evento

    4

    Sua aplicação processa o evento e responde com HTTP 200

    Sua URL deve responder com HTTP 200 em até 10 segundos. Respostas fora desse prazo são tratadas como falha e o evento é reenviado.

    Como Configurar

    Via plataforma (recomendado)

    1. 1Acesse https://app3.gwhats.app
    2. 2Vá em Configurações → Integrações
    3. 3Clique em "Webhooks"
    4. 4Clique em "Adicionar novo webhook"
    5. 5Insira sua URL e selecione os eventos
    6. 6Clique em "Criar"

    Via API

    Use o endpoint POST /api/v1/accounts/{account_id}/webhooks

    bash
    curl -X POST "https://app3.gwhats.app/api/v1/accounts/1/webhooks" \
  -H "api_access_token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meusite.com/webhook",
    "subscriptions": [
      "message_created",
      "conversation_created",
      "contact_created"
    ]
  }'

    Listar webhooks configurados

    bash
    curl "https://app3.gwhats.app/api/v1/accounts/1/webhooks" \
  -H "api_access_token: SEU_TOKEN"

    Atualizar um webhook

    bash
    curl -X PUT "https://app3.gwhats.app/api/v1/accounts/1/webhooks/1" \
  -H "api_access_token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://novaurl.com/webhook",
    "subscriptions": ["message_created"]
  }'

    Remover um webhook

    bash
    curl -X DELETE "https://app3.gwhats.app/api/v1/accounts/1/webhooks/1" \
  -H "api_access_token: SEU_TOKEN"

    Eventos

    Clique em cada evento para ver o payload completo que será enviado para sua URL.

    Segurança

    Para garantir que os webhooks recebidos são realmente do GWhats, valide o header X-GWhats-Signature usando HMAC-SHA256 com o segredo gerado na criação do webhook.

    Boas práticas

    • Sempre valide a assinatura antes de processar o evento
    • Use HTTPS — nunca HTTP para sua URL de webhook
    • Responda rapidamente (200) e processe o evento de forma assíncrona
    • Torne seu endpoint idempotente — eventos podem ser enviados mais de uma vez

    Validação da assinatura (Node.js)

    javascript
    const crypto = require('crypto');

function verificarAssinatura(payload, assinatura, segredo) {
  const hmac = crypto.createHmac('sha256', segredo);
  hmac.update(JSON.stringify(payload));
  const calculado = hmac.digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(calculado),
    Buffer.from(assinatura)
  );
}

app.post('/webhook/gwhats', (req, res) => {
  const assinatura = req.headers['x-gwhats-signature'];
  const segredo = process.env.GWHATS_WEBHOOK_SECRET;

  if (!verificarAssinatura(req.body, assinatura, segredo)) {
    return res.status(401).json({ error: 'Assinatura inválida' });
  }

  // processar evento com segurança...
  res.status(200).json({ received: true });
});

    Validação da assinatura (Python)

    python
    import hmac
import hashlib
import json

def verificar_assinatura(payload, assinatura, segredo):
    calculado = hmac.new(
        segredo.encode(),
        json.dumps(payload).encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(calculado, assinatura)

@app.route('/webhook/gwhats', methods=['POST'])
def webhook():
    assinatura = request.headers.get('X-GWhats-Signature', '')
    segredo = os.environ['GWHATS_WEBHOOK_SECRET']

    if not verificar_assinatura(request.json, assinatura, segredo):
        return jsonify({'error': 'Assinatura inválida'}), 401

    # processar evento com segurança...
    return jsonify({'received': True}), 200

    Retentativas

    Se sua URL retornar um erro (status ≠ 2xx) ou não responder em 10 segundos, o GWhats tentará reenviar o evento automaticamente.

    TentativaAguardaObservação
    1ª (original)ImediatoEnvio logo após o evento
    2ª tentativa~5 minutosPrimeiro reenvio após falha
    3ª tentativa~30 minutosÚltimo reenvio — após isso o evento é descartado

    Idempotência: como o mesmo evento pode chegar mais de uma vez, use o campo id do payload para deduplicar eventos já processados.

    Exemplos de Código

    Node.js + Express — receber e responder

    javascript
    const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook/gwhats', (req, res) => {
  const { event, conversation, sender, content } = req.body;

  switch (event) {
    case 'message_created':
      if (sender.type === 'contact') {
        console.log(`[MENSAGEM] ${sender.name}: ${content}`);
        // encaminhar para CRM, notificar equipe, etc.
      }
      break;

    case 'conversation_created':
      console.log(`[CONVERSA] Nova de ${conversation.contact?.name}`);
      break;

    case 'conversation_status_changed':
      console.log(`[STATUS] Conversa ${req.body.id} → ${req.body.status}`);
      break;

    case 'contact_created':
      console.log(`[CONTATO] Novo: ${req.body.name}`);
      break;
  }

  // OBRIGATÓRIO: responder 200 em até 10s
  res.status(200).json({ received: true });
});

app.listen(3000);

    Python + Flask

    python
    from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook/gwhats', methods=['POST'])
def webhook():
    data = request.json
    event = data.get('event')

    if event == 'message_created':
        sender = data.get('sender', {})
        content = data.get('content', '')
        if sender.get('type') == 'contact':
            print(f"[MENSAGEM] {sender.get('name')}: {content}")

    elif event == 'conversation_created':
        print(f"[CONVERSA] Nova conversa ID {data.get('id')}")

    elif event == 'conversation_status_changed':
        print(f"[STATUS] Conversa {data.get('id')} → {data.get('status')}")

    elif event == 'contact_created':
        print(f"[CONTATO] Novo contato: {data.get('name')}")

    return jsonify({'received': True}), 200

if __name__ == '__main__':
    app.run(port=3000)

    PHP

    php
    <?php

$payload = json_decode(file_get_contents('php://input'), true);
$event = $payload['event'] ?? '';

switch ($event) {
    case 'message_created':
        $sender = $payload['sender'] ?? [];
        $content = $payload['content'] ?? '';
        if ($sender['type'] === 'contact') {
            error_log("[MENSAGEM] {$sender['name']}: {$content}");
        }
        break;

    case 'conversation_created':
        error_log("[CONVERSA] Nova conversa ID {$payload['id']}");
        break;

    case 'conversation_status_changed':
        error_log("[STATUS] Conversa {$payload['id']} → {$payload['status']}");
        break;

    case 'contact_created':
        error_log("[CONTATO] Novo: {$payload['name']}");
        break;
}

// OBRIGATÓRIO: responder 200
http_response_code(200);
header('Content-Type: application/json');
echo json_encode(['received' => true]);

    n8n — configuração rápida

    Use o nó Webhook do n8n para receber eventos do GWhats sem escrever código:

    1. 1No n8n, adicione um nó "Webhook" e copie a URL gerada
    2. 2No GWhats, vá em Configurações → Integrações → Webhooks
    3. 3Cole a URL do n8n e selecione os eventos desejados
    4. 4No n8n, conecte o nó Webhook a ações como "Send Email", "HTTP Request" para o seu CRM, etc.
    5. 5Ative o workflow e pronto — eventos chegam em tempo real