Prezentare generală Webhooks (Webhooks Overview)

Webhook-urile livrează notificări HTTP POST în timp real către serverul dumneavoastră când apar evenimente în legătură cu comenzile. Aceasta elimină necesitatea de a interoga periodic API-ul pentru actualizări de stare.

Evenimente suportate

Payload-ul Webhook

Când apare un eveniment, Vignetim trimite o cerere POST către URL-ul înregistrat cu următoarea structură:

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

Anteturi de livrare

Fiecare livrare webhook include următoarele anteturi:

Verificarea semnăturii

Verificați întotdeauna semnătura webhook-ului pentru a vă asigura că payload-ul este autentic și nu a fost modificat.

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

Politica de reîncercare

Dacă endpoint-ul dumneavoastră nu returnează un răspuns 2xx în 10 secunde, Vignetim reîncearcă livrarea:

După ce toate cele 3 încercări de reîncercare eșuează, livrarea este marcată ca eșuată.

Dezactivare automată

Dacă un endpoint webhook acumulează 10 eșecuri consecutive de livrare, acesta este dezactivat automat. Va trebui să îl reactivați din API sau din panoul de control al partenerului. Utilizați endpoint-ul de test (POST /webhooks/:id/test) pentru a verifica conectivitatea înainte de reactivare.