Управление на Webhooks

Управлявайте вашите webhook крайни точки за получаване на известия за събития в реално време. Можете да регистрирате до 10 webhook крайни точки на организация.

Създаване на Webhook

POST /webhooks

Тяло на заявката

{
	"url": "https://yourapp.com/webhooks/vignetim",
	"events": ["order.completed", "order.failed"],
	"description": "Production order notifications"
}

Field	Type	Required	Описание
`url`	string	Yes	HTTPS URL адрес на крайната точка за получаване на webhook доставки
`events`	string[]	Yes	Масив от типове събития, за които да се абонирате (или `["*"]` за всички)
`description`	string	No	Четимо от човек описание на тази крайна точка

Отговор (201 Created)

{
	"id": "wh-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
	"url": "https://yourapp.com/webhooks/vignetim",
	"events": ["order.completed", "order.failed"],
	"description": "Production order notifications",
	"active": true,
	"signingSecret": "whs_a1b2c3d4e5f6789012345678901234567890abcdef",
	"createdAt": "2026-03-20T14:30:00.000Z"
}

Важно: signingSecret се връща само при първоначалното създаване на webhook-а. Съхранете го на сигурно място -- ще ви е необходим за верификация на входящите webhook подписи. Не може да бъде извлечен повторно.

SSRF защита

URL адресите на webhook-ове трябва да бъдат публично достъпни HTTPS крайни точки. Следните се отхвърлят:

Частни/вътрешни IP адреси (10.x.x.x, 172.16-31.x.x, 192.168.x.x)
Localhost и loopback адреси
Не-HTTPS URL адреси

Списък на Webhooks

GET /webhooks

Отговор

{
	"data": [
		{
			"id": "wh-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
			"url": "https://yourapp.com/webhooks/vignetim",
			"events": ["order.completed", "order.failed"],
			"description": "Production order notifications",
			"active": true,
			"consecutiveFailures": 0,
			"createdAt": "2026-03-20T14:30:00.000Z",
			"updatedAt": "2026-03-20T14:30:00.000Z"
		}
	]
}

Актуализиране на Webhook

PUT /webhooks/:id

Параметри на пътя

Name	Type	Required	Описание
`id`	string	Yes	ID на webhook-а

Тяло на заявката

{
	"url": "https://yourapp.com/webhooks/vignetim-v2",
	"events": ["*"],
	"description": "Updated to receive all events"
}

Всички полета са опционални. Само предоставените полета се актуализират.

Отговор

Връща актуализирания webhook обект.

Изтриване на Webhook

DELETE /webhooks/:id

Параметри на пътя

Name	Type	Required	Описание
`id`	string	Yes	ID на webhook-а

Отговор

Връща 204 No Content при успех.

Тестване на Webhook

Изпратете тестово събитие, за да проверите дали вашата крайна точка е достъпна и обработва правилно доставките на webhook-ове.

POST /webhooks/:id/test

Параметри на пътя

Name	Type	Required	Описание
`id`	string	Yes	ID на webhook-а

Отговор

{
	"success": true,
	"statusCode": 200,
	"responseTime": 145,
	"message": "Test webhook delivered successfully"
}

Ако тестовата доставка е неуспешна:

{
	"success": false,
	"statusCode": 500,
	"responseTime": 10000,
	"message": "Webhook endpoint returned non-2xx status code"
}