Webhook'lara Genel Bakış (Webhooks Overview)

Webhook'lar, siparişlerinizde olaylar gerçekleştiğinde sunucunuza gerçek zamanlı HTTP POST bildirimleri gönderir. Bu, durum güncellemeleri için API'yi yoklama (polling) ihtiyacını ortadan kaldırır.

Desteklenen Olaylar

Webhook Yükü (Payload)

Bir olay gerçekleştiğinde, Vignetim kayıtlı URL'nize aşağıdaki yapıda bir POST isteği gönderir:

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

Teslimat Başlıkları (Delivery Headers)

Her webhook teslimatı aşağıdaki başlıkları içerir:

İmza Doğrulama

Yükün özgün olduğundan ve değiştirilmediğinden emin olmak için webhook imzasını her zaman doğrulayın.

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

Yeniden Deneme Politikası (Retry Policy)

Uç noktanız 10 saniye içinde 2xx yanıtı döndürmezse, Vignetim teslimatı yeniden dener:

3 yeniden deneme girişiminin tümü başarısız olursa, teslimat başarısız olarak işaretlenir.

Otomatik Devre Dışı Bırakma (Auto-Disable)

Bir webhook uç noktası art arda 10 teslimat hatası biriktirirse otomatik olarak devre dışı bırakılır. API üzerinden veya partner kontrol panelinizden yeniden etkinleştirmeniz gerekecektir. Yeniden etkinleştirmeden önce bağlantıyı doğrulamak için test uç noktasını (POST /webhooks/:id/test) kullanın.