← 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
- Como administrador, abre Integraciones › Webhooks y crea un nuevo webhook.
- Indica un título, la URL de tu endpoint y los eventos que debe recibir.
- 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.
Siguiente: Seguridad y cabeceras de los webhooks