Descripción general de webhooks

Los webhooks entregan notificaciones HTTP POST en tiempo real a su servidor cuando ocurren eventos en sus pedidos. Esto elimina la necesidad de consultar la API periódicamente (polling) para obtener actualizaciones de estado.

Eventos soportados

Evento	Descripción
`order.completed`	Un pedido se ha completado totalmente y todos los productos han sido entregados
`order.failed`	Un pedido ha fallado (fallo en el pago o error de aprovisionamiento)
`order.refunded`	Un pedido ha sido reembolsado
`order.cancelled`	Un pedido ha sido cancelado
`*`	Comodín (wildcard) -- recibir todos los eventos

Carga útil del webhook

Cuando ocurre un evento, Vignetim envía una solicitud POST a su URL registrada con la siguiente estructura:

{
	"event": "order.completed",
	"timestamp": "2026-03-20T14:31:15.000Z",
	"data": {
		"orderId": "ord-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
		"status": "COMPLETED",
		"externalReference": "YOUR-ORDER-REF-001",
		"products": [
			{
				"productId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
				"productTypeId": 1,
				"status": "COMPLETED"
			}
		],
		"total": {
			"amount": 11.5,
			"currency": "EUR"
		},
		"completedAt": "2026-03-20T14:31:15.000Z"
	}
}

Encabezados de entrega

Cada entrega de webhook incluye los siguientes encabezados:

Encabezado	Descripción
`X-Webhook-Signature`	Firma hexadecimal HMAC-SHA256 del cuerpo de la solicitud, firmada con el `signingSecret` del webhook
`X-Webhook-Event`	El tipo de evento (p. ej., `order.completed`)
`X-Webhook-Timestamp`	Marca de tiempo ISO 8601 de cuándo se generó el evento
`Content-Type`	`application/json`

Verificación de firma

Siempre verifique la firma del webhook para asegurarse de que la carga útil (payload) es auténtica y no ha sido manipulada.

import crypto from 'crypto';

function verifyWebhookSignature(body, signature, secret) {
	const expected = crypto.createHmac('sha256', secret).update(body).digest('hex');

	return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

// In your webhook handler:
app.post('/webhooks/vignetim', (req, res) => {
	const signature = req.headers['x-webhook-signature'];
	const rawBody = req.rawBody; // Ensure you capture the raw body

	if (!verifyWebhookSignature(rawBody, signature, 'whs_your-webhook-signing-secret')) {
		return res.status(401).send('Invalid signature');
	}

	const event = req.body;
	console.log(`Received event: ${event.event}`);

	// Process the event...

	res.status(200).send('OK');
});

Política de reintentos

Si su endpoint no devuelve una respuesta 2xx dentro de 10 segundos, Vignetim reintenta la entrega:

Intento	Retraso
1er reintento	Inmediato
2do reintento	1 segundo
3er reintento	5 segundos

Después de que los 3 intentos de reintento fallen, la entrega se marca como fallida.

Desactivación automática

Si un endpoint de webhook acumula 10 fallos de entrega consecutivos, se desactiva automáticamente. Deberá reactivarlo desde la API o su panel de control de socio. Use el endpoint de prueba (POST /webhooks/:id/test) para verificar la conectividad antes de reactivarlo.