Вебхуки

POST https://api.beatapi.io/v1/webhooks

Создайте endpoint вебхука для необязательных уведомлений о завершении задач BeatAPI.

Авторизация

Authorization   string   обязательный

Передавайте API-ключ BeatAPI как токен Bearer. Создать ключ можно в панели управления.

Authorization: Bearer <BEATAPI_API_KEY>

Храните постоянные API-ключи на доверенных серверах. Для тела запроса обязателен Content-Type: application/json. Если метод принимает Idempotency-Key, этот заголовок необязателен, но рекомендуется для безопасных повторных попыток с точно таким же телом.

Тело запроса

url   string   обязательный

Общедоступный HTTPS-адрес для получения событий задач BeatAPI. Не используйте localhost или адрес частной сети.

Формат: uri

description   string   необязательный

Необязательная внутренняя метка для поиска endpoint в вашем аккаунте.

events   string[]   необязательный

События задач, которые нужно получать. Если поле не указано, подписка включает task.succeeded и task.failed.

Ответ

Успешный запрос возвращает HTTP 201.

{
  "data": {
    "id": "wh_9aBcD",
    "object": "webhook_endpoint",
    "url": "https://example.com/beatapi-webhook",
    "description": "Production webhook",
    "events": [
      "task.succeeded",
      "task.failed"
    ],
    "status": "active",
    "secret": "whsec_example_store_this_once",
    "created_at": 1782210000,
    "updated_at": 1782210000
  }
}

Проверка подписей уведомлений

При каждой доставке BeatAPI отправляет x-beatapi-event, x-beatapi-timestamp и x-beatapi-signature. Вычислите ожидаемую подпись HMAC-SHA256 в шестнадцатеричном виде для строки:

timestamp + "." + raw_request_body

Используйте secret, возвращённый при создании endpoint. Сравнивайте подписи за постоянное время, проверяйте точные исходные байты до разбора JSON и отклоняйте временные метки старше 5 минут, чтобы ограничить атаки повторного воспроизведения.

Управление endpoint вебхуков

• GET /v1/webhooks возвращает список endpoint вебхуков.
• GET /v1/webhooks/{id} возвращает сведения об endpoint вебхука.
• PATCH /v1/webhooks/{id} обновляет endpoint вебхука.
• DELETE /v1/webhooks/{id} удаляет endpoint вебхука.

Следующий шаг

Проверяйте подпись каждого уведомления до разбора его данных. Если доставка задержалась или не состоялась, источником истины остаётся статус из GET /v1/tasks/{task_id}.

Ошибки