Webhookok áttekintése (Webhooks Overview)

A webhookok valós idejű HTTP POST értesítéseket küldenek a szerverére, amikor események történnek a megrendeléseinél. Ez kiküszöböli az API lekérdezésének szükségességét az állapotfrissítésekhez.

Támogatott események

Webhook tartalom (Webhook Payload)

Amikor egy esemény bekövetkezik, a Vignetim POST kérést küld a regisztrált URL-re a következő struktúrával:

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

Kézbesítési fejlécek (Delivery Headers)

Minden webhook kézbesítés a következő fejléceket tartalmazza:

Aláírás ellenőrzés (Signature Verification)

Mindig ellenőrizze a webhook aláírást annak biztosítása érdekében, hogy a tartalom hiteles és nem lett módosítva.

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

// A webhook kezelőjében:
app.post('/webhooks/vignetim', (req, res) => {
	const signature = req.headers['x-webhook-signature'];
	const rawBody = req.rawBody; // Biztosítsa a nyers törzs rögzítését

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

	// Esemény feldolgozása...

	res.status(200).send('OK');
});

Újrapróbálkozási szabályzat (Retry Policy)

Ha a végpont nem ad vissza 2xx választ 10 másodpercen belül, a Vignetim újrapróbálja a kézbesítést:

A 3 újrapróbálkozási kísérlet sikertelensége után a kézbesítés sikertelenként lesz megjelölve.

Automatikus letiltás (Auto-Disable)

Ha egy webhook végpont 10 egymást követő kézbesítési hibát halmoz fel, automatikusan letiltásra kerül. Az API-ból vagy a partner vezérlőpultról kell újra engedélyeznie. Használja a teszt végpontot (POST /webhooks/:id/test) a kapcsolat ellenőrzéséhez az újraengedélyezés előtt.