Guía de webhooks

1. Cree un punto final de webhook

Primero, cree un punto final HTTP en su aplicación que pueda recibir solicitudes POST de LicenseChain.

// Express.js Example
app.post('/webhooks/licensechain', async (req, res) => {'{'}
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const payload = JSON.stringify(req.body);
  
  // Verify signature (see Security section)
  if (!verifySignature(payload, signature, timestamp, webhookSecret)) {'{'}
    return res.status(401).send('Invalid signature');
  {'}'}
  
  // Process webhook event
  const event = req.body;
  console.log('Received event:', event.type, event.data);
  
  res.status(200).send('OK');
{'}'});

2. Registre su webhook

Utilice la API LicenseChain para registrar su punto final de webhook. Deberá proporcionar la URL y especificar qué eventos desea recibir.

POST /v1/webhooks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{'{'}
  "url": "https://your-app.com/webhooks/licensechain",
  "events": ["license.created", "license.updated", "license.revoked"],
  "secret": "optional-custom-secret"
{'}'}

3. Eventos disponibles

LicenseChain admite los siguientes eventos de webhook:

Firmas de webhooks

Todas las solicitudes de webhook incluyen una firma en el X-Webhook-Signature encabezamiento. La firma es HMAC-SHA256 del cuerpo de la solicitud sin formato que utiliza su secreto de webhook. Siempre verifique usando comparación de tiempo constante (e.g. crypto.timingSafeEqual) para evitar ataques de sincronización. El valor del encabezado puede ser hexadecimal sin formato o sha256= seguido de hexadecimal; pelar el sha256= prefijo antes de comparar buffers hexadecimales para que las longitudes coincidan.

// Node.js Example (constant-time, supports sha256= prefix)
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {'{'}
  if (!payload || !signature || !secret) return false;
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  const received = String(signature).startsWith('sha256=') ? String(signature).slice(7) : String(signature);
  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(received, 'hex');
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
{'}'}

// In your webhook handler (use raw body for payload)
const signature = req.headers['x-webhook-signature'];
const payload = req.rawBody || JSON.stringify(req.body);
if (!verifySignature(payload, signature, webhookSecret)) {'{'}
  return res.status(401).send('Invalid signature');
{'}'}

Encabezados de solicitud

LicenseChain incluye los siguientes encabezados con cada solicitud de webhook:

Listar todos los webhooks

GET /v1/webhooks?page=1&limit=10
Authorization: Bearer YOUR_API_KEY

Obtener detalles del webhook

GET /v1/webhooks/:id
Authorization: Bearer YOUR_API_KEY

Actualizar webhook

PUT /v1/webhooks/:id
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{'{'}
  "url": "https://new-url.com/webhooks",
  "events": ["license.created", "license.updated"]
{'}'}

Eliminar webhook

DELETE /v1/webhooks/:id
Authorization: Bearer YOUR_API_KEY

Enviar webhook de prueba

Puede probar el punto final de su webhook sin esperar a que ocurra un evento real:

POST /v1/webhooks/:id/test
Authorization: Bearer YOUR_API_KEY

Esto enviará un evento de prueba a la URL de su webhook con una carga útil de muestra. Utilice esto para verificar que su punto final esté funcionando correctamente.

Ver registros de webhook

Verifique el estado de entrega y la respuesta para cada evento de webhook:

GET /v1/webhooks/:id/logs?page=1&limit=10
Authorization: Bearer YOUR_API_KEY

Los registros incluyen el código de estado HTTP, el cuerpo de la respuesta y si la entrega se realizó correctamente.

✅ Verifique siempre las firmas

Nunca procese eventos de webhook sin verificar la firma. Esto garantiza que la solicitud provenga de LicenseChain y no haya sido manipulada.

✅ Responde rápidamente

Su punto final de webhook debería responder en 5 segundos. Para operaciones de larga duración, reconozca el webhook inmediatamente y procese de forma asincrónica.

✅ Manejar la idempotencia

Utilice el ID del evento para evitar procesar el mismo evento varias veces. Almacene los ID de eventos procesados ​​y compruébelos antes de procesarlos.

✅ Utilice HTTPS

Utilice siempre HTTPS para los puntos finales de su webhook para garantizar que los datos estén cifrados en tránsito.

✅ Supervisar registros de webhooks

Verifique periódicamente los registros de webhooks para identificar y solucionar problemas de entrega. Configure alertas para entregas fallidas.

Webhook no recibe eventos

• • Verifique que la URL de su webhook sea accesible desde Internet.
• • Verifique que su terminal devuelva un código de estado 2xx
• • Asegúrese de que los eventos a los que está suscrito realmente estén ocurriendo
• • Revisar los registros de webhooks para detectar errores de entrega.

Falla en la verificación de firma

• • Asegúrese de que está utilizando el secreto de webhook correcto
• • Verifique que esté firmando el cuerpo exacto de la solicitud (como cadena JSON)
• • Verifique que esté utilizando el algoritmo HMAC-SHA256
• • Asegúrese de que los encabezados se lean correctamente (distingue entre mayúsculas y minúsculas)

Errores de tiempo de espera

• • Optimice su controlador de webhook para responder rápidamente
• • Traslade el procesamiento pesado a trabajos en segundo plano
• • Devuelve 200 OK inmediatamente y procesa de forma asincrónica