Основы Webhooks
Webhooks позволяют серверам информировать клиентов о событиях в реальном времени, без необходимости постоянных запросов от клиента.
Краткое описание
Webhook представляет собой HTTP-обратный вызов, который сервер отправляет на предоставленный клиентом адрес, когда происходит определённое событие. Webhooks используются для уведомления о платежах, изменениях статуса, уведомлениях, интеграциях и других событиях. В отличие от Polling API, где клиент периодически проверяет наличие новых данных, при использовании webhooks сервер активно отправляет данные клиенту. Хорошо реализованный webhook учитывает безопасность, надёжность, идемпотентность, стратегии повтора и обработку ошибок. Webhooks представляют собой важный паттерн для архитектур, основанных на событиях, и современных интеграций между сервисами.
Основные компоненты
Источник события и целевая система
Источник события — это сервер, который запускает webhook. Целевая система — это клиентский адрес, который получает webhook. Обе системы должны взаимодействовать через HTTP, а целевая система должна быть публично доступна, если сервер находится вне собственной сети.
Регистрация URL webhook
Клиент регистрирует URL адрес в источнике события, на который будут отправляться webhooks. Обычно это осуществляется через приборную панель или API. Важно, чтобы URL использовал HTTPS и был валидирован для предотвращения манипуляций.
Payload и формат события
Payload — это содержимое webhook, как правило в формате JSON. Он содержит информацию о событии, такую как тип события, временная метка, затронутый ресурс и подробности. Уникальное поле Event-ID помогает выявить дубликаты.
Безопасность и подписи
Webhooks должны быть подписаны, чтобы получатель мог проверить, что сообщение действительно поступило из ожидаемого источника. Подписи HMAC-SHA256 над payload являются распространённым методом. Получатель проверяет подпись с использованием общего секрета или открытого ключа.
Идемпотентность при webhooks
Webhooks могут быть отправлены несколько раз из-за таймаутов или повторов. Получатель должен обрабатывать события идемпотентно, используя уникальный Event-ID. События с одинаковыми Event-ID должны игнорироваться или отбрасываться после обработки.
Стратегии повтора
Если получатель не отвечает кодом успеха, источник события должен повторить отправку webhook. Повторы должны выполняться с экспоненциальной задержкой, чтобы не перегружать целевую систему. После определённого количества попыток или истечения временного окна источник события должен прекратить попытки и отметить событие как неудачное.
Ожидаемые коды ответов
Целевая система должна ответить кодом 2xx при успешном получении. Коды 4xx указывают на то, что получатель отклоняет или не может обработать запрос. Коды 5xx свидетельствуют о временной проблеме, которая оправдывает повтор. Неправильный код может привести к ошибочным повторам или отмене событий.
Таймауты
Источник события должен установить таймаут, после которого он считает запрос неудачным. Получатели должны быстро подтверждать получение webhooks и выполнять более длительную обработку асинхронно в фоне, чтобы избежать таймаутов.
Логирование и мониторинг Webhooks
Обе стороны должны логировать webhooks, включая Event-ID, временную метку, HTTP-статус и время отклика. Мониторинг помогает выявить сбои, задержки и частоту ошибок. Приборные панели статуса доставки особенно полезны.
Тестирование и отладка Webhooks
Для разработки подходят инструменты вроде ngrok, локальные тестеры webhooks или песочницы. Они помогают получать, проверять и отлаживать webhooks локально, без необходимости развёртывания публичных серверов.
Практический пример
Платёжный сервис хочет информировать своих клиентов об успешном платеже. Клиент регистрирует URL webhook:
POST /api/v1/webhooks
Content-Type: application/json
Authorization: Bearer token
{
"url": "https://shop.example.com/webhooks/payments",
"events": ["payment.succeeded", "payment.failed"]
}Когда платёж успешен, платёжный сервис отправляет webhook:
POST /webhooks/payments
Content-Type: application/json
X-Event-ID: evt-9876543210abcdef
X-Webhook-Signature: sha256=5d41402abc4b2a76b9719d911017c592
{
"eventType": "payment.succeeded",
"eventId": "evt-9876543210abcdef",
"timestamp": "2026-07-01T12:34:56Z",
"data": {
"paymentId": "pay-123456",
"orderId": "order-7890",
"amount": 79.97,
"currency": "EUR"
}
}Получатель проверяет подпись, сохраняет Event-ID и обрабатывает платёж. Он отвечает 200 OK для подтверждения успешной доставки. При таймауте или ошибке 5xx платёжный сервис повторяет отправку с экспоненциальной задержкой.
FAQ: Основы Webhooks
1. Что такое webhook?
2. Чем webhooks отличаются от Polling?
3. Как зарегистрировать webhook?
4. Почему webhooks должны использовать HTTPS?
5. Что такое подпись webhook?
6. Как работает идемпотентность при webhooks?
7. Что такое экспоненциальная задержка?
8. Какие коды ответов должен возвращать получатель webhook?
9. Что происходит, если webhook не может быть доставлен?
10. Что такое Dead Letter Queue для webhooks?
11. Должна ли обработка webhook быть синхронной или асинхронной?
12. Как тестировать webhooks локально?
13. Что такое Event-ID?
14. Какие меры безопасности важны для webhooks?
15. Что такое Webhook Replay?
Продолжаем путь изучения API
Следующая статья в нашем пути посвящена GraphQL API Entwicklung: Schemas, Resolvers, Subscriptions und Apollo — альтернативе REST с гибким запросом данных и типизированной схемой.
Источники
Книги по разработке API
Чтобы углубить знания о вебхуках, проектировании API и архитектуре программного обеспечения, рекомендуем следующие книги:
Keine Bücher für Kategorie "api-development" gefunden.