Como usar Webhooks?
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