Управление Webhooks (Webhook Management)

Управляйте эндпоинтами вебхуков для получения уведомлений о событиях в реальном времени. Вы можете зарегистрировать до 10 эндпоинтов вебхуков на организацию.

Создание вебхука

text

POST /webhooks

Тело запроса

json

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

Поле	Тип	Обязательное	Описание
`url`	string	Да	HTTPS URL эндпоинта для получения доставок вебхуков
`events`	string[]	Да	Массив типов событий для подписки (или `["*"]` для всех)
`description`	string	Нет	Понятное описание данного эндпоинта

Ответ (201 Created)

json

{
	"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 возвращается только при первом создании вебхука. Сохраните его в безопасном месте -- он понадобится для проверки входящих подписей вебхуков. Повторно получить его невозможно.

Защита от SSRF

URL вебхуков должны быть публично доступными HTTPS-эндпоинтами. Следующие адреса отклоняются:

Частные/внутренние IP-адреса (10.x.x.x, 172.16-31.x.x, 192.168.x.x)
Localhost и loopback-адреса
URL без HTTPS

Список вебхуков

text

GET /webhooks

Ответ

json

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

Обновление вебхука

text

PUT /webhooks/:id

Параметры пути

Имя	Тип	Обязательный	Описание
`id`	string	Да	ID вебхука

Тело запроса

json

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

Все поля необязательные. Обновляются только предоставленные поля.

Ответ

Возвращает обновлённый объект вебхука.

Удаление вебхука

text

DELETE /webhooks/:id

Параметры пути

Имя	Тип	Обязательный	Описание
`id`	string	Да	ID вебхука

Ответ

Возвращает 204 No Content при успешном выполнении.

Тестирование вебхука

Отправьте тестовое событие для проверки доступности вашего эндпоинта и корректной обработки доставок вебхуков.

text

POST /webhooks/:id/test

Параметры пути

Имя	Тип	Обязательный	Описание
`id`	string	Да	ID вебхука

Ответ

json

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

Если тестовая доставка не удалась:

json

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