Получить настройки Webhook

GET

/api/v1/webhook

Для пользователей из материкового Китая: используйте https://api.toapis.cn в качестве эндпоинта (Base URL). Замените https://api.toapis.com на https://api.toapis.cn во всех примерах этого документа.

Поведение

Читает webhook-конфигурацию указанного ключа: адрес обратного вызова, состояние включения и состояние последних доставок. Конфигурация одна на модельный ключ. Мягко удалённые ключи читаются.

Возвращается только secret_configured — признак наличия секрета, сам секрет не возвращается. Неустановленные адрес и время дают null. Время в управляющих API — RFC 3339. При ошибке чтения статуса health.state=unknown — это не значит, что запись конфигурации не удалась.

Аутентификация

Authorizationstringзаголовокобязательно

Используйте системный токен Bearer YOUR_SYSTEM_ACCESS_TOKEN. Доступ ограничен вашим аккаунтом. Ключи моделей не принимаются. X-User-Id не нужен. Обхода через права администратора или команды нет.

Параметры запроса

api_key_idintegerзапрособязательно

Положительный целочисленный ID собственного обычного ключа модели, не секрет sk- и не токен доступа. Параметр запроса должен быть положительным целым; пропуск и null отклоняются.

Отсутствующий или неположительный api_key_id даёт 400; отсутствующий или чужой ключ — 404; при лимите — 429. mode=off ограничивает только записи и на это чтение не влияет.

Примеры запросов

Пример запроса

curl --request GET \
  --url 'https://api.toapis.com/api/v1/webhook?api_key_id=123' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'

Примеры ответов

Пример ответа

{
  "code": 0,
  "message": "",
  "data": {
    "api_key_id": 123,
    "enabled": false,
    "url": null,
    "secret_configured": false,
    "previous_secret_expires_at": null,
    "updated_at": null,
    "mode": "enforce",
    "health": {
      "state": "disabled",
      "failure_kind": null,
      "consecutive_failures": 0,
      "suspended_until": null,
      "last_http_status": null,
      "last_failure_at": null
    }
  }
}

Первое подключение

Вызовите POST /api/v1/webhook/rotate-secret, чтобы сгенерировать секрет подписи. secret возвращается только один раз в этом ответе — сразу сохраните его на стороне приёмника. Инициализация сама по себе не включает колбэки.
Настройте проверку подписи на приёмнике, как описано ниже.
Вызовите PATCH /api/v1/webhook с URL колбэка и enabled=true. При первом включении или смене URL создаётся проверочное событие endpoint.test, а в ответе возвращается verification_event_id.
Вызовите POST /api/v1/webhook/test, чтобы отправить тестовое событие, или запросите GET /api/v1/webhook/events/{event_id} для проверки результата доставки.

Проверка подписи

Каждый запрос колбэка несёт три заголовка: X-ToAPIs-Webhook-Id (ID события), X-ToAPIs-Webhook-Timestamp (метка времени в Unix-секундах) и X-ToAPIs-Webhook-Signature (подпись).

Для проверки соедините ID события, метку времени и исходное тело запроса через . в event_id.timestamp.raw_body, вычислите HMAC-SHA256 с сохранённым секретом и сравните с шестнадцатеричным дайджестом после v1= в заголовке подписи.

Проверяйте именно исходные байты тела — не разбирайте JSON и не сериализуйте заново. В период ротации секрета заголовок подписи может содержать несколько значений v1= через запятую. Достаточно совпадения любого. Дедупликация на приёмнике — по ID события.

В payload колбэка и метке подписи используются Unix-секунды, а в управляющих эндпоинтах — RFC 3339.