Přehled webhooků (Webhooks Overview)

Webhooky doručují HTTP POST oznámení v reálném čase na váš server, když nastanou události ve vašich objednávkách. Tím odpadá nutnost dotazovat se API na aktualizace stavu.

Podporované události

Payload webhooku

Když nastane událost, Vignetim odešle POST požadavek na vaši zaregistrovanou URL s následující strukturou:

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

Hlavičky doručení

Každé doručení webhooku obsahuje následující hlavičky:

Ověření podpisu

Vždy ověřte podpis webhooku, abyste zajistili, že payload je autentický a nebyl pozměněn.

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

Zásady opakování

Pokud váš endpoint nevrátí odpověď 2xx do 10 sekund, Vignetim zopakuje doručení:

Po selhání všech 3 pokusů o opakování je doručení označeno jako neúspěšné.

Automatické vypnutí

Pokud webhook endpoint nahromadí 10 po sobě jdoucích selhání doručení, je automaticky deaktivován. Budete ho muset znovu aktivovat z API nebo z vašeho partnerského řídicího panelu. Před opětovnou aktivací použijte testovací endpoint (POST /webhooks/:id/test) k ověření konektivity.