Вебхуки¶

Регистрируйте исходящие HTTP-вебхуки, которые срабатывают при событиях записи в API (изменения страниц, медиафайлов и пользователей, обновления конфигурации, установки через GPM, обновления Grav). У каждого вебхука есть URL, список фильтров событий, необязательные собственные заголовки, сгенерированный секрет для подписи HMAC и журнал доставок.

Разрешения: api.webhooks.read / api.webhooks.write. Секреты генерируются сервером и всегда маскируются в ответах API, кроме одного раза — в ответе, создающем вебхук.

Допустимые имена событий¶

* (все), page.created, page.updated, page.deleted, page.moved, page.translated, pages.reordered, media.uploaded, media.deleted, user.created, user.updated, user.deleted, config.updated, gpm.installed, gpm.removed, grav.upgraded.

Доставки¶

Каждая доставка — это JSON POST вида {"event": "...", "timestamp": "<ISO 8601>", "data": {...}, "webhook_id": "wh_..."}. Grav добавляет к каждой доставке следующие заголовки:

Собственные headers вебхука могут задавать другие заголовки, включая Content-Type и User-Agent, но не могут заменить эти три: создание или обновление вебхука с одним из них возвращает 422. Принимаются только URL http и https, а URL, который разрешается в приватный, loopback-, link-local или зарезервированный адрес, отклоняется — как при сохранении, так и повторно во время доставки. Перенаправления не выполняются.

Вебхук, у которого 5 доставок подряд завершились неудачей, автоматически отключается с указанием disabled_reason; успешная доставка сбрасывает счётчик. Хранятся последние 50 доставок каждого вебхука.

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

GET /webhooks

Выводит все настроенные вебхуки. Секреты маскируются (первые 6 и последние 4 символа сохраняются, середина скрыта).

Ответ

{"data": [{"id": "wh_abc123", "url": "https://example.com/hooks/grav", "secret": "whsec_************************************************a1b2", "events": ["page.created", "page.updated"], "enabled": true, "headers": {}, "created": 1774008000, "failure_count": 0}]}

Коды ответов

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

POST /webhooks

Регистрирует новый вебхук. URL должен быть абсолютным URL http или https, который не разрешается в приватный или зарезервированный адрес. События (если переданы) должны быть из разрешённого списка (см. вводную главу). Сервер генерирует идентификатор вебхука и секрет для подписи; ответ — единственный раз, когда возвращается полный секрет.

Параметры

Запрос

{"url": "https://example.com/hooks/grav", "events": ["page.created", "page.updated"], "enabled": true}

Ответ

{"data": {"id": "wh_abc123", "url": "https://example.com/hooks/grav", "secret": "whsec_0123456789abcdef0123456789abcdef0123456789abcdef", "events": ["page.created", "page.updated"], "enabled": true, "headers": {}, "created": 1774526400, "failure_count": 0}}

Коды ответов

Получение вебхука¶

GET /webhooks/{id}

Возвращает один вебхук по id. Секрет маскируется. Ответ содержит заголовок ETag.

Параметры

Ответ

{"data": {"id": "wh_abc123", "url": "https://example.com/hooks/grav", "secret": "whsec_************************************************a1b2", "events": ["page.created", "page.updated"], "enabled": true, "headers": {}, "created": 1774008000, "failure_count": 0}}

Коды ответов

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

PATCH /webhooks/{id}

Частичное обновление: меняются только переданные поля. url, events и headers проверяются так же, как при создании. Секрет изменить нельзя. Повторное включение автоматически отключённого вебхука не сбрасывает его failure_count; это делает следующая успешная доставка.

Параметры

Запрос

{"url": "https://example.com/hooks/grav-v2", "events": ["page.created", "page.updated", "page.deleted"]}

Ответ

{"data": {"id": "wh_abc123", "url": "https://example.com/hooks/grav-v2", "secret": "whsec_************************************************a1b2", "events": ["page.created", "page.updated", "page.deleted"], "enabled": true, "headers": {}, "created": 1774008000, "failure_count": 0}}

Коды ответов

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

DELETE /webhooks/{id}

Удаляет вебхук. История доставок также удаляется.

Параметры

Коды ответов

Журнал доставок¶

GET /webhooks/{id}/deliveries

Журнал доставок одного вебхука с постраничной разбивкой, сначала новые. Каждая запись содержит идентификатор доставки, событие, URL, отправленные заголовки и тело запроса, статус ответа и первые 1000 символов тела ответа, длительность, флаг успеха, error для транспортных сбоев и метку времени Unix created. Хранятся только последние 50 доставок.

Параметры

Ответ

{"data": [{"id": "dlv_9f2c4e1a7b3d5f60", "event": "page.updated", "url": "https://example.com/hooks/grav", "request_headers": {"Content-Type": "application/json", "User-Agent": "Grav-Webhook/1.0", "X-Grav-Signature": "5d41402abc4b2a76b9719d911017c592...", "X-Grav-Event": "page.updated", "X-Grav-Delivery": "dlv_9f2c4e1a7b3d5f60"}, "request_body": {"event": "page.updated", "timestamp": "2026-09-21T12:00:00+00:00", "data": {"page": {"route": "/blog/hello", "title": "Hello", "slug": "hello"}}, "webhook_id": "wh_abc123"}, "created": 1790000000, "status_code": 200, "response_body": "ok", "duration_ms": 142, "success": true}], "meta": {"pagination": {"page": 1, "per_page": 20, "total": 1, "total_pages": 1}}, "links": {"self": "/api/v1/webhooks/wh_abc123/deliveries?page=1&per_page=20"}}

Коды ответов

Тестовая доставка вебхука¶

POST /webhooks/{id}/test

Отправляет тестовую доставку (событие test с data.message, равным This is a test webhook delivery.) на URL вебхука и сразу возвращает запись доставки. Она подписывается и журналируется как настоящая доставка, а неудачный тест учитывается при автоматическом отключении после 5 сбоев как одна доставка. Используйте его, чтобы проверить, что эндпоинт доступен и проверяет подпись, не дожидаясь реального события. Возвращает 502 с той же записью доставки в теле, если получатель отвечает статусом вне 2xx или недоступен.

Параметры

Ответ

{"data": {"id": "dlv_1a2b3c4d5e6f7a8b", "event": "test", "url": "https://example.com/hooks/grav", "request_headers": {"Content-Type": "application/json", "User-Agent": "Grav-Webhook/1.0", "X-Grav-Signature": "5d41402abc4b2a76b9719d911017c592...", "X-Grav-Event": "test", "X-Grav-Delivery": "dlv_1a2b3c4d5e6f7a8b"}, "request_body": {"event": "test", "timestamp": "2026-09-21T12:00:00+00:00", "data": {"message": "This is a test webhook delivery."}, "webhook_id": "wh_abc123"}, "created": 1790000000, "status_code": 200, "response_body": "ok", "duration_ms": 118, "success": true}}

Коды ответов