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.