PATCH/v1/webhooks/{webhook_id}

Изменить вебхук

update_webhook

Меняет URL, описание, подписки, доступ, фильтры, собственные заголовки, авторизацию исходящих запросов и признак включения. active: true включает вебхук и снимает паузу, так что накопленные доставки уходят по порядку. active: false отключает вебхук и отменяет ожидающие доставки. headers заменяет весь список собственных заголовков; элемент без value сохраняет прежнее значение заголовка с тем же именем. auth: null и data_profile_id: null удаляют авторизацию исходящих запросов и профиль доступа.

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

Передайте ключ API в заголовке Authorization: Authorization: Bearer <ключ>.

Параметры пути

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

Параметры заголовков

Idempotency-Keystring
Ключ для безопасного повтора записи: от 1 до 255 печатных символов ASCII; рекомендуется UUID v4 на каждую логическую операцию. Повтор с тем же ключом в течение 24 часов не выполняет операцию заново: он возвращает сохранённый ответ (статус, заголовки и тело) с заголовком Idempotency-Replayed: true. Тот же ключ с другим методом, путём, Content-Type или телом — ответ 409 api.idempotency_mismatch; пока первый запрос ещё выполняется — 409 api.idempotency_in_progress с Retry-After: 1. После ответа 5xx или 429 ключ освобождается, и повтор выполняет операцию заново. Ключ действует в пределах организации и вызывающей стороны (ключ API, пользователь или ключ своего источника).
length ≥ 1, length ≤ 255

Тело запроса

application/json

Объект: WebhookUpdate

urlstring | null
length ≤ 2048
descriptionstring | null
length ≤ 200
eventsarray of WebhookEventFilter | null
items ≥ 1
activeboolean | null
rolestring | null
Допустимые значения: admineditorviewernull
data_profile_idinteger | null
null удаляет профиль доступа.
collection_idsarray of integer | null
Коллекции вебхука. Пустой список — все коллекции, доступные по роли и профилю доступа; отсутствие значения или null оставляет их без изменений. Ключ, который сам ограничен коллекциями, видит и меняет только вебхуки, коллекции которых входят в его список (на другие вебхуки возвращается 404 webhooks.not_found). Пустой список или коллекция вне его списка возвращают 403 webhooks.collections_outside_key.
items ≤ 200
tagsarray of string | null
items ≤ 50
payloadstring | null
Допустимые значения: fullthinnull
headersarray of WebhookHeaderInput | null
items ≤ 10
authWebhookAuthInput | null
null удаляет авторизацию исходящих запросов.

Ответы

200Успешный ответ

Заголовки ответа

RateLimit-Policy
Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.
RateLimit
Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).
X-RateLimit-Remaining
Сколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-Reset
Через сколько секунд сбросится самый строгий лимит.
Idempotency-Replayed
true — ответ воспроизведён из сохранённого для этого Idempotency-Key: операция повторно не выполнялась.

application/json

Объект: WebhookEndpoint

idintegerобязательно
urlstringобязательно
descriptionstringобязательно
eventsarray of WebhookEventFilterобязательно
activebooleanобязательно
statusWebhookStatusобязательно
paused_atstring (date-time) | null
paused_reasonstring | null
failures — 10 неудачных попыток подряд; feature_disabled — тариф не включает вебхуки.
disabled_reasonstring | null
gone — получатель ответил 410; manual — отключён администратором.
Допустимые значения: gonemanualnull
disabled_atstring (date-time) | null
roleWebhookRoleобязательно
data_profile_idinteger | null
Профиль доступа вебхука (null — без профиля, как у ключа API с той же ролью).
collection_idsarray of integerобязательно
Коллекции, о которых вебхук получает события; пусто — все коллекции, доступные роли и профилю доступа.
tagsarray of stringобязательно
События карточек — только по карточкам с любым из этих тегов; пусто — без фильтра.
payloadWebhookPayloadModeобязательно
headersarray of WebhookHeaderобязательно
auth_typestring | null
Тип авторизации исходящих запросов (null — нет).
Допустимые значения: bearerbasicnull
auth_setbooleanобязательно
Задана ли авторизация исходящих запросов (значения никогда не возвращаются).
previous_secret_valid_untilstring (date-time) | null
До какого момента доставки подписываются ещё и прежним секретом (null — перекрытия нет).
healthWebhookHealth
consecutive_failuresintegerобязательно
last_delivery_atstring (date-time) | null
last_success_atstring (date-time) | null
last_errorstring | null
created_byinteger | null
created_by_namestring | null
created_atstring (date-time)обязательно
updated_atstring (date-time)обязательно

400Запрос неверен: значение параметра или состояние объекта не позволяет выполнить действие (`detail` — сообщение).

Заголовки ответа

RateLimit-Policy
Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.
RateLimit
Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).
X-RateLimit-Remaining
Сколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-Reset
Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

401Учётные данные не переданы (нет ни cookie сессии, ни ключа API) или ключ не найден.

Заголовки ответа

RateLimit-Policy
Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.
RateLimit
Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).
X-RateLimit-Remaining
Сколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-Reset
Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

403Действие запрещено: недостаточно прав роли, нет доступа к коллекции или карточке, запрос выполняется в режиме «Смотреть как» либо организация приостановлена или удалена (`detail` — объект с `code: org_suspended | org_deleted`).

Заголовки ответа

RateLimit-Policy
Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.
RateLimit
Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).
X-RateLimit-Remaining
Сколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-Reset
Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

404Объект не существует или вам недоступен. API не подтверждает существование объекта с ограниченным доступом.

Заголовки ответа

RateLimit-Policy
Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.
RateLimit
Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).
X-RateLimit-Remaining
Сколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-Reset
Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

422Ошибка проверки: тело или параметры не соответствуют схеме (`detail` — список ошибок проверки) либо значение параметра вне допустимого диапазона (`detail` — сообщение).

Заголовки ответа

RateLimit-Policy
Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.
RateLimit
Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).
X-RateLimit-Remaining
Сколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-Reset
Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

429Слишком много запросов (`api.rate_limited`), квота организации на минуту, день или месяц исчерпана (`api.quota_exceeded`; в `error.details` — `quota`, `limit` и `reset_at`), достигнут лимит организации или сервис ответов занят (`answers.engine_busy`). Подождите время, указанное в заголовке `Retry-After`.

Заголовки ответа

Retry-After
Сколько секунд подождать перед повтором запроса.
RateLimit-Policy
Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.
RateLimit
Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).
X-RateLimit-Remaining
Сколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-Reset
Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

Коды ошибок

Коды, которые эта операция может вернуть в error.code, помимо общих кодов любого запроса.

Безопасные повторы

Передавайте заголовок Idempotency-Key (например, UUID) с каждым POST и PATCH. Повтор с тем же ключом в течение 24 часов возвращает сохранённый ответ, а не выполняет запрос снова.

Лимиты частоты

В ответах есть заголовки RateLimit и RateLimit-Policy, а также прежние X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. В ответе 429 есть Retry-After в секундах: подождите и повторите запрос.

← webhooks · Справочник API

curl -X PATCH 'https://api.sursa.com/v1/webhooks/1' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/webhooks/sursa","description":"Customer support articles","events":["card.*"]}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Попробовать

Ключ API

Ключ хранится только в памяти этой вкладки и отправляется только на https://api.sursa.com.

Запросы работают с настоящими данными вашей организации.

Idempotency-Key header

webhook_id path *

Idempotency-Key

Если поле пустое, для каждого запроса создаётся новый ключ.

Тело запроса (JSON)