Os Webhooks do Wootdesk permitem que sistemas externos recebam eventos em tempo real sempre que algo acontece dentro da plataforma.

Eles funcionam como callbacks HTTP automáticos: quando um evento ocorre no Wootdesk, uma requisição POST é enviada para a URL configurada.

Você pode usar webhooks para:

• Integrações com CRMs

• Automação de processos

• Integração com IA

• Monitoramento em tempo real

• Disparo de workflows

• Sincronização de dados

• Notificações externas

Como adicionar um Webhook?

Passo 1

Acesse:

Configurações → Integrações → Webhooks

Depois clique em:

Configure

Passo 2

Clique em:

Adicionar novo webhook

Uma janela será aberta para configuração.

Você deverá informar:

• URL do endpoint que receberá os eventos

• Eventos que deseja escutar

Isso permite receber apenas eventos relevantes para sua aplicação.

Como funciona?

Sempre que um evento ocorrer, o Wootdesk enviará uma requisição HTTP POST para sua URL.

Exemplo de payload enviado pelo Wootdesk

{
  "event": "message_created",
  "id": "1",
  "content": "Olá",
  "created_at": "2020-03-03 13:05:57 UTC",
  "message_type": "incoming",
  "content_type": "text",
  "content_attributes": {},
  "source_id": "",
  "sender": {
    "id": "1",
    "name": "Agente",
    "email": "[email protected]"
  },
  "contact": {
    "id": "1",
    "name": "Cliente"
  },
  "conversation": {
    "display_id": "1"
  },
  "account": {
    "id": "1",
    "name": "Wootdesk"
  }
}

Principais eventos suportados

conversation_created

Disparado quando uma nova conversa é criada.

conversation_updated

Disparado quando algum atributo da conversa é alterado.

Exemplo:

• status

• prioridade

• atribuição

• labels

conversation_status_changed

Disparado quando o status muda.

Exemplo:

• open

• pending

• resolved

• snoozed

message_created

Disparado quando uma nova mensagem é enviada.

Muito utilizado para:

• bots

• IA

• integrações externas

message_updated

Disparado quando uma mensagem é editada.

webwidget_triggered

Disparado quando o visitante abre o widget do chat.

Muito útil para:

• tracking

• analytics

• automações de engajamento

conversation_typing_on

Disparado quando um agente começa a digitar.

conversation_typing_off

Disparado quando o agente para de digitar.

Objetos disponíveis nos payloads

Os eventos podem incluir diversos objetos.

Account

Informações da conta.

{
  "id": "1",
  "name": "Minha Empresa"
}

Inbox

Informações da inbox.

{
  "id": "1",
  "name": "Suporte"
}

Contact

Informações do cliente.

{
  "id": "1",
  "name": "João"
}

User

Informações do agente/admin.

{
  "id": "1",
  "name": "Maria"
}

Conversation

Dados completos da conversa.

Inclui:

• status

• mensagens

• agente

• cliente

• timestamps

• navegador

• origem

• canal

Message

Dados completos da mensagem.

Inclui:

• conteúdo

• remetente

• tipo

• anexos

• atributos

Verificação de segurança dos Webhooks

O Wootdesk assina todas as requisições utilizando HMAC SHA256.

Isso garante que:

• o payload veio realmente do Wootdesk

• ninguém alterou os dados no caminho

Headers enviados pelo Wootdesk

X-Wootdesk-Signature
X-Wootdesk-Timestamp
X-Wootdesk-Delivery

Como a assinatura funciona

A assinatura é gerada usando:

sha256=HMAC-SHA256(secret, "{timestamp}.{raw_body}")

Onde:

• secret → segredo do webhook

• timestamp → timestamp enviado no header

• raw_body → body original da requisição

Processo de verificação

1. Ler os headers

Pegue:

• assinatura

• timestamp

2. Ler o body bruto

⚠️ Importante:
Não parseie/reformate o JSON antes da validação.

Use o body bruto exatamente como recebido.

3. Gerar assinatura localmente

Utilize o mesmo algoritmo HMAC SHA256.

4. Comparar assinaturas

Faça comparação segura (constant-time compare).

Exemplo em Node.js

const crypto = require("crypto");

function verifySignature(rawBody, timestamp, receivedSignature, secret) {
  const message = `${timestamp}.${rawBody}`;

  const expected =
    "sha256=" +
    crypto
      .createHmac("sha256", secret)
      .update(message)
      .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(receivedSignature)
  );
}

Exemplo em Python

import hmac
import hashlib

def verify_signature(raw_body, timestamp, received_signature, secret):
    message = f"{timestamp}.".encode() + raw_body

    expected = "sha256=" + hmac.new(
        secret.encode(),
        message,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, received_signature)

Boas práticas

Sempre valide a assinatura

Nunca confie diretamente nos payloads recebidos.

Rejeite timestamps antigos

Uma boa prática é rejeitar requisições com mais de:

• 5 minutos

Isso evita replay attacks.

Use HTTPS

Sempre utilize endpoints HTTPS.

Responda rapidamente

O webhook deve responder rápido:

• 200 OK

Processamentos pesados devem ir para filas/background jobs.

Casos de uso comuns

IA / Agent Bots

Enviar mensagens para:

• OpenAI

• Claude

• Gemini

CRM

Criar leads automaticamente.

ERP

Sincronizar pedidos e clientes.

Slack / Discord

Notificar equipes.

Automação

Integrar com:

• n8n

• Make

• Zapier

• Pipedream

Diferença entre Webhooks e WebSocket

Webhooks

• Comunicação servidor → servidor

• Baseado em eventos HTTP

• Melhor para integrações backend

WebSocket

• Conexão em tempo real contínua

• Atualizações instantâneas

• Melhor para dashboards/apps em tempo real

Dica estratégica

Uma arquitetura muito poderosa no Wootdesk é:

• Webhooks

• Automations

• Agent Bots

• APIs

• WebSockets

Combinados.

Isso permite criar:

• suporte totalmente automatizado

• IA híbrida

• atendimento omnichannel inteligente

• sincronização em tempo real

• workflows enterprise avançados