Webhooks apžvalga

Webhooks pristatymo mechanizmas siunčia realaus laiko HTTP POST pranešimus į jūsų serverį, kai įvyksta įvykiai su jūsų užsakymais. Tai pašalina poreikį reguliariai apklausti API dėl būsenos atnaujinimų.

Palaikomi įvykiai

Webhook duomenų struktūra

Kai įvyksta įvykis, Vignetim siunčia POST užklausą į jūsų registruotą URL su šia struktūra:

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

Pristatymo antraštės

Kiekvienas webhook pristatymas apima šias antraštes:

Parašo patikrinimas

Visada patikrinkite webhook parašą, kad įsitikintumėte, jog duomenys yra autentiški ir nebuvo pakeisti.

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

Pakartotinių bandymų politika

Jei jūsų galinis taškas negrąžina 2xx atsakymo per 10 sekundžių, Vignetim pakartoja pristatymą:

Po visų 3 pakartotinių bandymų nesėkmės, pristatymas pažymimas kaip nepavykęs.

Automatinis išjungimas

Jei webhook galinis taškas surenka 10 iš eilės nesėkmingų pristatymų, jis automatiškai išjungiamas. Turėsite jį iš naujo įjungti per API arba partnerio valdymo skydelį. Naudokite testinį galinį tašką (POST /webhooks/:id/test), kad patikrintumėte ryšį prieš iš naujo įjungdami.