← Guides

Configurar webhooks

Recibe notificaciones HTTP en tiempo real cuando ocurren eventos en el CRM, sin necesidad de consultas periódicas.

Requisitos previos

  • Un usuario administrador en el CRM: los webhooks se crean en la pantalla del CRM, no por la API con un Service Account
  • Un endpoint HTTPS accesible públicamente para recibir eventos

Paso 1: Elige los eventos

Los eventos están listados en Eventos disponibles. Con el token de un Service Account también puedes consultar la lista que tu cuenta acepta:

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" }
    ]
  }
]

Paso 2: Crea el webhook en el CRM

  1. Como administrador, abre Integraciones › Webhooks y crea un nuevo webhook.
  2. Indica un título, la URL de tu endpoint y los eventos que debe recibir.
  3. Elige la autenticación HMAC y define un secret. Tu endpoint usa el mismo secret para validar cada entrega.

Paso 3: Validar la firma HMAC

Cada entrega de webhook incluye un header X-Webhook-Signature. Verifícalo siempre para evitar suplantaciones:

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 });
});

Paso 4: Confirma rápido

Responde con un estado 2xx en cuanto la firma sea válida y haz el trabajo pesado después. Las entregas que fallan o exceden el tiempo se reenvían: consulta la política de reenvío. El contenido de data depende del evento: registra el cuerpo de las primeras entregas mientras construyes la integración.