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

Eveniment	Descriere
`order.completed`	O comandă a fost finalizată complet și toate produsele au fost livrate
`order.failed`	O comandă a eșuat (eșec de plată sau eroare de aprovizionare)
`order.refunded`	O comandă a fost rambursată
`order.cancelled`	O comandă a fost anulată
`*`	Wildcard -- primiți toate evenimentele

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:

Antet	Descriere
`X-Webhook-Signature`	Semnătura hex HMAC-SHA256 a corpului cererii, semnată cu `signingSecret`-ul webhook-ului
`X-Webhook-Event`	Tipul evenimentului (de ex., `order.completed`)
`X-Webhook-Timestamp`	Marca temporală ISO 8601 a momentului generării evenimentului
`Content-Type`	`application/json`

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:

Încercare	Întârziere
Prima reîncercare	Imediat
A doua reîncercare	1 secundă
A treia reîncercare	5 secunde

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.