Apercu des webhooks (Webhooks Overview)

Les webhooks livrent des notifications HTTP POST en temps reel a votre serveur lorsque des evenements surviennent sur vos commandes. Cela elimine le besoin d'interroger l'API (polling) pour les mises a jour de statut.

Evenements pris en charge

Charge utile du webhook (Webhook Payload)

Lorsqu'un evenement survient, Vignetim envoie une requete POST a votre URL enregistree avec la structure suivante :

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

En-tetes de livraison

Chaque livraison de webhook inclut les en-tetes suivants :

Verification de la signature

Verifiez toujours la signature du webhook pour vous assurer que la charge utile est authentique et n'a pas ete alteree.

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

Politique de nouvelle tentative (Retry Policy)

Si votre endpoint ne retourne pas une reponse 2xx dans les 10 secondes, Vignetim reessaie la livraison :

Apres l'echec des 3 tentatives de nouvelle livraison, la livraison est marquee comme echouee.

Desactivation automatique

Si un endpoint webhook accumule 10 echecs de livraison consecutifs, il est automatiquement desactive. Vous devrez le reactiver depuis l'API ou votre tableau de bord partenaire. Utilisez l'endpoint de test (POST /webhooks/:id/test) pour verifier la connectivite avant de le reactiver.