Configurar Webhooks

Receba notificações HTTP em tempo real quando eventos ocorrem no CRM — sem necessidade de polling.

Pré-requisitos

Um usuário administrador no CRM: os webhooks são criados na tela do CRM, não pela API com Service Account
Um endpoint HTTPS publicamente acessível para receber eventos

Passo 1: Escolha os eventos

Os eventos estão listados em Eventos disponíveis. Com o token de um Service Account você também consulta a lista que a sua conta aceita:

cURL

curl https://minha-empresa.platform-api.magnetcustomer.com/api/webhooks/triggers \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200

[
  {
    "_id": "Oportunidades",
    "triggers": [
      { "key": "deal.created", "label": "Oportunidade criada", "group": "deal", "groupName": "Oportunidades" },
      { "key": "deal.won", "label": "Oportunidade ganha", "group": "deal", "groupName": "Oportunidades" }
    ]
  }
]

Passo 2: Crie o webhook no CRM

Como administrador, abra Integrações › Webhooks e crie um novo webhook.
Informe um título, a URL do seu endpoint e os eventos que ele deve receber.
Escolha a autenticação HMAC e defina um secret. O seu endpoint usa o mesmo secret para validar cada entrega.

Passo 3: Validar assinatura HMAC

Cada entrega de webhook inclui um header X-Webhook-Signature. Sempre verifique para evitar spoofing:

Express.js

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = `sha256=${crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex')}`;

  const sigBuffer = Buffer.from(signature ?? '', 'utf8');
  const expBuffer = Buffer.from(expected, 'utf8');

  if (sigBuffer.length !== expBuffer.length) return false;

  return crypto.timingSafeEqual(sigBuffer, expBuffer);
}

app.post('/webhooks/crm', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-webhook-signature'] as string;
  const valid = verifyWebhookSignature(req.body.toString(), sig, process.env.WEBHOOK_SECRET!);

  if (!valid) return res.status(401).json({ error: 'Invalid signature' });

  const event = JSON.parse(req.body.toString());
  console.log('Event received:', event.event);

  res.json({ received: true });
});

Passo 4: Confirme rápido

Responda com um status 2xx assim que a assinatura for válida e faça o trabalho pesado depois. Entregas que falham ou estouram o tempo são reenviadas: veja a política de reenvio. O conteúdo de data depende do evento: registre o corpo das primeiras entregas enquanto monta a integração.

Próximo: Segurança e cabeçalhos dos webhooks