Como usar webhooks

Use este guia para configurar webhooks e receber eventos da IAra em sistemas externos.

O que são webhooks

Webhooks são chamadas HTTP enviadas pela IAra quando algo acontece na conta, como criação de mensagem, mudança de conversa ou evento operacional. Eles permitem integrar a IAra com CRMs, ERPs, automações, data warehouses e ferramentas internas.

Criar webhook

1. Acesse Configurações > Integrações > Webhooks.
2. Clique em Adicionar novo webhook.
3. Informe a URL que receberá requisições POST.
4. Selecione os eventos que deseja assinar.
5. Salve e faça um teste controlado.

Exemplo de payload

{
  "event": "message_created",
  "id": "1",
  "content": "Olá",
  "created_at": "2026-06-01T13:05:57Z",
  "message_type": "incoming",
  "content_type": "text",
  "content_attributes": {},
  "source_id": "",
  "sender": {
    "id": "1",
    "name": "Maria Souza",
    "email": "[email protected]"
  },
  "contact": {
    "id": "1",
    "name": "Maria Souza"
  },
  "conversation": {
    "display_id": "42",
    "status": "open",
    "inbox_id": "10"
  },
  "account": {
    "id": "59",
    "name": "Minha conta"
  }
}

Eventos comuns

• message_created
• message_updated
• conversation_created
• conversation_updated
• conversation_status_changed
• conversation_typing_on
• conversation_typing_off

Verificar assinatura do webhook

Quando disponível na conta, a IAra assina as requisições para que seu servidor confirme que o payload não foi adulterado.

Cabeçalhos esperados:

• X-IAra-Signature
• X-IAra-Timestamp
• X-IAra-Delivery

A assinatura segue o formato:

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

Exemplo em Node.js

const crypto = require('crypto');

function verifySignature(rawBody, timestamp, receivedSignature, secret) {
  const expected =
    'sha256=' +
    crypto
      .createHmac('sha256', secret)
      .update(`${timestamp}.${rawBody}`)
      .digest('hex');

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

Boas práticas

• Responda rápido com status 2xx.
• Processe tarefas demoradas em fila.
• Registre event, id, horário e payload bruto.
• Valide assinatura antes de confiar no payload.