Обзор Webhooks

Вебхуки (webhooks) доставляют HTTP POST-уведомления в реальном времени на ваш сервер при возникновении событий с вашими заказами. Это исключает необходимость опроса API для получения обновлений статуса.

Поддерживаемые события

Структура данных вебхука

При возникновении события Vignetim отправляет POST-запрос на зарегистрированный URL со следующей структурой:

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

Заголовки доставки

Каждая доставка вебхука включает следующие заголовки:

Проверка подписи

Всегда проверяйте подпись вебхука, чтобы убедиться в подлинности данных и отсутствии их подмены.

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

Политика повторных попыток

Если ваш эндпоинт не возвращает ответ 2xx в течение 10 секунд, Vignetim повторяет доставку:

После неудачи всех 3 повторных попыток доставка помечается как неуспешная.

Автоматическое отключение

Если эндпоинт вебхука накопит 10 последовательных неудачных доставок, он автоматически отключается. Вам потребуется повторно активировать его через API или панель управления партнёра. Используйте тестовый эндпоинт (POST /webhooks/:id/test) для проверки связи перед повторной активацией.