Webhooks Overview

Webhooks deliver real-time HTTP POST notifications to your server when events occur on your orders. This eliminates the need to poll the API for status updates.

Supported Events

Webhook Payload

When an event occurs, Vignetim sends a POST request to your registered URL with the following structure:

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

Delivery Headers

Each webhook delivery includes the following headers:

Signature Verification

Always verify the webhook signature to ensure the payload is authentic and has not been tampered with.

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

Retry Policy

If your endpoint does not return a 2xx response within 10 seconds, Vignetim retries delivery:

After all 3 retry attempts fail, the delivery is marked as failed.

Auto-Disable

If a webhook endpoint accumulates 10 consecutive delivery failures, it is automatically disabled. You will need to re-enable it from the API or your partner dashboard. Use the test endpoint (POST /webhooks/:id/test) to verify connectivity before re-enabling.