Обновить настройки Webhook

PATCH

/api/v1/webhook

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

Поведение

Устанавливает или меняет адрес обратного вызова и состояние включения указанного ключа. Нужно передать хотя бы одно из enabled и url, опущенные поля сохраняют значения. Перед включением нужно настроить секрет и публичный HTTPS-адрес обратного вызова.

Один enabled=false только выключает колбэки и сохраняет адрес и секрет. url=null очищает адрес и разрешён только при окончательном отключении.

При первом включении или смене URL также создаётся проверочное событие endpoint.test, в ответе возвращается verification_event_id. Сохранение конфигурации не означает, что приёмник прошёл проверку.

Отключение отменяет только события в pending: оно не отзывает доставляемые запросы, не отменяет задачи и не делает возвратов. Повторное включение не восстанавливает события cancelled.

После смены URL прошлые события сохраняют адрес, записанный при создании, и на новый адрес не пересылаются.

Записи недоступны для мягко удалённых ключей и ключей со scope. Отключённые, просроченные и исчерпанные ключи настраивать можно. Ограничение частоты общее с операциями записи жизненного цикла ключей: не более 10 запросов на запись в минуту на пользователя.

JSON запроса — объект верхнего уровня до 16384 байт, дедлайн чтения тела 10 секунд. Параметры запроса, неизвестные и повторные поля отклоняются. api_key_id нужно указывать явно.

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

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

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

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

api_key_idintegerтелообязательно

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

enabledbooleanтело

Включить или отключить обратные вызовы.

urlstring | nullтело

Публичный HTTPS URL или null.

Недопустимые поля или JSON — 400; недопустимый URL — 400 (code=16014); отсутствующий или чужой ключ — 404; неполная конфигурация при включении — 409 (code=16015); включение или смена URL, требующие проверки при mode=off, — 409 (code=16016); при лимите — 429.

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

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

curl --request PATCH \
  --url 'https://api.toapis.com/api/v1/webhook' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"api_key_id":123,"enabled":false}'

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

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

{
  "code": 0,
  "message": "",
  "data": {
    "api_key_id": 123,
    "enabled": false,
    "url": null,
    "secret_configured": false,
    "previous_secret_expires_at": null,
    "updated_at": "2026-11-13T00:00:00Z",
    "mode": "enforce",
    "health": {
      "state": "disabled",
      "failure_kind": null,
      "consecutive_failures": 0,
      "suspended_until": null,
      "last_http_status": null,
      "last_failure_at": null
    },
    "verification_event_id": null
  }
}

Порядок подключения и проверку подписи см. в Получить настройки Webhook.