# Webhooks - Krayin CRM v2.1.6

Configuração e uso de webhooks para integração em tempo real.

📋 Índice

Visão Geral

Eventos Disponíveis

Configuração

Payload dos Eventos

Validação de Assinatura

Retry Policy

Exemplos Práticos

Visão Geral

Webhooks permitem que o Krayin CRM notifique sistemas externos quando eventos ocorrem, sem necessidade de polling.

┌─────────────────┐      Evento       ┌─────────────────┐
│   Krayin CRM    │  ─────────────►  │   Seu Sistema   │
│  (Lead criado)  │   POST JSON       │   (N8N, etc)    │
└─────────────────┘                   └─────────────────┘

Eventos Disponíveis

Leads

Evento	Trigger
`leads.created`	Novo lead criado
`leads.updated`	Lead modificado
`leads.deleted`	Lead deletado
`leads.converted`	Lead convertido para oportunidade

Contacts

Evento	Trigger
`contacts.created`	Novo contato/organização criado
`contacts.updated`	Contato modificado
`contacts.deleted`	Contato deletado

Activities

Evento	Trigger
`activities.created`	Nova atividade criada
`activities.updated`	Atividade modificada
`activities.completed`	Atividade marcada como concluída

Quotes

Evento	Trigger
`quotes.created`	Nova cotação criada
`quotes.updated`	Cotação modificada
`quotes.sent`	Cotação enviada ao cliente

Configuração

Via Interface Admin

Acesse: Settings → Webhooks

Clique em Criar Webhook

Preencha:
- Nome: Identificador (ex: "N8N - Novos Leads")
- Entity Type: Entidade que dispara (Leads, Contacts, etc)
- Events: Eventos desejados (created, updated, deleted)
- URL: Endpoint que receberá o webhook
- Headers: Headers customizados (opcional)
- Active: Ativar/Desativar

Via API

curl -X POST "https://crm.memudecore.com.br/api/v1/webhooks" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "N8N - Leads Sync",
    "entity_type": "leads",
    "events": ["created", "updated", "converted"],
    "url": "https://n8n.memudecore.com.br/webhook/krayin-leads",
    "headers": {
      "Authorization": "Bearer meu_webhook_secret",
      "X-Source": "krayin-crm"
    },
    "is_active": true
  }'

Payload dos Eventos

Estrutura Geral

{
  "id": "webhook_trigger_abc123",
  "event": "leads.created",
  "entity_type": "leads",
  "timestamp": "2026-01-18T12:30:00Z",
  "data": {
    // Dados completos da entidade
  }
}

Lead Created

{
  "id": "wh_001",
  "event": "leads.created",
  "entity_type": "leads",
  "timestamp": "2026-01-18T12:30:00Z",
  "data": {
    "id": 42,
    "title": "Empresa ABC",
    "source_id": 1,
    "source": {
      "id": 1,
      "name": "WhatsApp"
    },
    "lead_type_id": 2,
    "sales_owner_id": 1,
    "sales_owner": {
      "id": 1,
      "name": "João Vendedor",
      "email": "joao@empresa.com"
    },
    "status_id": 1,
    "value": 5000,
    "expected_close_date": "2026-02-28",
    "description": "Lead interessado no plano premium",
    "contact_person": {
      "id": 5,
      "name": "Maria Silva",
      "email": "maria@abc.com"
    },
    "organization": {
      "id": 3,
      "name": "ABC Ltda"
    },
    "tags": ["whatsapp", "premium"],
    "created_at": "2026-01-18T12:30:00Z",
    "updated_at": "2026-01-18T12:30:00Z"
  }
}

Lead Updated

{
  "id": "wh_002",
  "event": "leads.updated",
  "entity_type": "leads",
  "timestamp": "2026-01-18T14:00:00Z",
  "data": {
    "id": 42,
    "title": "Empresa ABC",
    "value": 7500,
    "status_id": 2,
    "updated_at": "2026-01-18T14:00:00Z"
  },
  "changes": {
    "value": {
      "old": 5000,
      "new": 7500
    },
    "status_id": {
      "old": 1,
      "new": 2
    }
  }
}

Lead Converted

{
  "id": "wh_003",
  "event": "leads.converted",
  "entity_type": "leads",
  "timestamp": "2026-01-20T10:00:00Z",
  "data": {
    "lead_id": 42,
    "contact_created": true,
    "organization_created": false,
    "new_contact_id": 15,
    "converted_by": {
      "id": 1,
      "name": "João Vendedor"
    }
  }
}

Activity Created

{
  "id": "wh_004",
  "event": "activities.created",
  "entity_type": "activities",
  "timestamp": "2026-01-18T15:00:00Z",
  "data": {
    "id": 100,
    "type": "call",
    "title": "Ligação de follow-up",
    "description": "Confirmar interesse",
    "lead_id": 42,
    "lead": {
      "id": 42,
      "title": "Empresa ABC"
    },
    "scheduled_from": "2026-01-20T14:00:00Z",
    "scheduled_to": "2026-01-20T14:30:00Z",
    "is_done": false,
    "user": {
      "id": 1,
      "name": "João Vendedor"
    }
  }
}

Validação de Assinatura

O Krayin pode incluir uma assinatura HMAC-SHA256 para validar autenticidade.

Header de Assinatura

X-Krayin-Signature: sha256=abc123...

Validar em PHP

<?php
function validateWebhook($payload, $signature, $secret) {
    $expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);
    return hash_equals($expected, $signature);
}

// Uso
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_KRAYIN_SIGNATURE'] ?? '';
$secret = 'seu_webhook_secret';

if (!validateWebhook($payload, $signature, $secret)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($payload, true);
// Processar webhook...

Validar em Node.js

const crypto = require('crypto');

function validateWebhook(payload, signature, secret) {
    const expected = 'sha256=' + 
        crypto.createHmac('sha256', secret)
              .update(payload)
              .digest('hex');
    
    return crypto.timingSafeEqual(
        Buffer.from(expected),
        Buffer.from(signature)
    );
}

// Uso com Express
app.post('/webhook', (req, res) => {
    const signature = req.headers['x-krayin-signature'];
    const payload = JSON.stringify(req.body);
    
    if (!validateWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
        return res.status(401).send('Invalid signature');
    }
    
    // Processar webhook...
    res.status(200).send('OK');
});

Retry Policy

Quando um webhook falha, o Krayin tenta novamente automaticamente.

Política de Retry

Tentativa	Delay	Total Acumulado
1	Imediato	0
2	1 minuto	1 min
3	5 minutos	6 min
4	15 minutos	21 min
5	1 hora	1h 21min

Códigos de Resposta

Código	Comportamento
`2xx`	Sucesso, não retry
`4xx`	Erro do cliente, não retry (exceto 429)
`429`	Rate limit, retry com backoff
`5xx`	Erro do servidor, retry
Timeout	Retry

Resposta Esperada

Seu endpoint deve retornar:

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "received"}

Exemplos Práticos

Webhook para N8N

Configuração no Krayin:

{
  "name": "N8N - Todos os Leads",
  "entity_type": "leads",
  "events": ["created", "updated", "converted"],
  "url": "https://n8n.memudecore.com.br/webhook/abc123",
  "is_active": true
}

Workflow N8N:

1. Webhook Trigger
   - Method: POST
   - Path: /webhook/abc123

2. Switch Node (baseado em event)
   - leads.created → Criar tarefa no Asana
   - leads.updated → Atualizar Google Sheets
   - leads.converted → Enviar email de parabéns

3. HTTP Request para ações

Webhook para Slack

Enviar notificação quando lead é criado:

// Seu endpoint
app.post('/webhook/krayin-to-slack', async (req, res) => {
    const { event, data } = req.body;
    
    if (event === 'leads.created') {
        await fetch(process.env.SLACK_WEBHOOK_URL, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                text: `🎉 Novo Lead: ${data.title}`,
                blocks: [
                    {
                        type: 'section',
                        text: {
                            type: 'mrkdwn',
                            text: `*Novo Lead Criado*\n` +
                                  `*Título:* ${data.title}\n` +
                                  `*Valor:* R$ ${data.value}\n` +
                                  `*Vendedor:* ${data.sales_owner.name}`
                        }
                    }
                ]
            })
        });
    }
    
    res.status(200).json({ status: 'ok' });
});

Webhook para WhatsApp (Evolution API)

Notificar vendedor via WhatsApp quando lead é criado:

app.post('/webhook/krayin-to-whatsapp', async (req, res) => {
    const { event, data } = req.body;
    
    if (event === 'leads.created') {
        // Buscar telefone do vendedor
        const sellerPhone = await getSellerPhone(data.sales_owner_id);
        
        // Enviar mensagem via Evolution API
        await fetch('https://evolution.memudecore.com.br/message/sendText/instance', {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${process.env.EVOLUTION_API_KEY}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                number: sellerPhone,
                text: `🆕 *Novo Lead Atribuído*\n\n` +
                      `*${data.title}*\n` +
                      `Valor: R$ ${data.value || 'Não informado'}\n` +
                      `Fonte: ${data.source?.name || 'Não informada'}\n\n` +
                      `Acesse: https://crm.memudecore.com.br/admin/leads/view/${data.id}`
            })
        });
    }
    
    res.status(200).json({ status: 'ok' });
});

🔧 Debug de Webhooks

Verificar Logs

# Ver logs de webhooks enviados
docker exec krayin grep "webhook" storage/logs/laravel.log | tail -50

Testar Endpoint

# Simular webhook localmente
curl -X POST "http://localhost:3000/webhook/test" \
  -H "Content-Type: application/json" \
  -H "X-Krayin-Signature: sha256=test" \
  -d '{
    "event": "leads.created",
    "data": {"id": 1, "title": "Teste"}
  }'

Ferramentas Úteis

webhook.site - Endpoint temporário para debug

requestbin.com - Inspecionar payloads

ngrok - Expor localhost para testes

Última atualização: Janeiro 2026