Подключения и webhook

Все методы · Ключи и права · Ошибки

Примеры ответов сокращены. Пустой массив означает допустимый результат без доступных записей, а не обязательное отсутствие данных.

Для методов с ключом действуют общие проверки: 401 — ключ не принят, 403 — не хватает scope или прав владельца, 429 — превышен лимит. Неверные параметры могут дать 400, недоступный адресный ресурс — 404. Особенности команды указаны рядом с методом. Точную причину смотрите в error.code и details: как обработать ошибку и безопасно повторить запрос.

Получить webhook-подписки

GET /api/v1/webhooks

Действие ключа: webhooks:manage. Оно не заменяет права владельца на объекты и поля.

Дополнительно webhook.manage. Возвращаются настройки, не секрет подписи.

Параметры пути: нет. Тело: не требуется.

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

GET /api/v1/webhooks HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

Ответ и ошибки

Успех: 200. Массив подписок.

{
  "data": [],
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

Создать webhook-подписку

POST /api/v1/webhooks

Действие ключа: webhooks:manage. Оно не заменяет права владельца на объекты и поля.

Нужен предварительно настроенный секрет по secretRef и разрешённый HTTPS endpoint. filters необязателен. retryPolicy: maxAttempts 1–10 (default 3), baseDelayMs 1–3 600 000 (default 1000). По умолчанию включено; пример намеренно disabled до проверки получателя.

Параметры пути: нет. Тело: JSON; пример ниже показывает основные поля.

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

POST /api/v1/webhooks HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "code": "sample-webhook",
  "endpoint": "https://receiver.example.invalid/events",
  "secretRef": "SECRET_REFERENCE",
  "executionPrincipalId": "PRINCIPAL_ID",
  "eventTypes": [
    "ObjectCreated"
  ],
  "enabled": false
}

Ответ и ошибки

Успех: 201. Подписка.

{
  "data": {
    "id": "SUBSCRIPTION_ID",
    "enabled": false
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Получить доставки webhook

GET /api/v1/webhook-deliveries

Действие ключа: webhooks:manage. Оно не заменяет права владельца на объекты и поля.

Необязательный subscriptionId ограничивает список одной подпиской.

Параметры пути: нет. Тело: не требуется.

Query-пример: subscriptionId=SUBSCRIPTION_ID.

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

GET /api/v1/webhook-deliveries?subscriptionId=SUBSCRIPTION_ID HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

Ответ и ошибки

Успех: 200. Массив доставок.

{
  "data": [],
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

Создать входящее подключение

POST /api/v1/integrations

Действие ключа: integrations:manage. Оно не заменяет права владельца на объекты и поля.

Нужны code, type, executionPrincipalId. Поддержанные входящие команды: object.create, object.update, comment.add. config задаёт mapping/typeDefinitionId или visibility. Пример сохраняет выключенным; управление включением — интерфейс интеграций.

Параметры пути: нет. Тело: JSON; пример ниже показывает основные поля.

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

POST /api/v1/integrations HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "code": "sample-inbound",
  "type": "inbound-webhook",
  "executionPrincipalId": "PRINCIPAL_ID",
  "enabled": false,
  "config": {
    "command": "object.create",
    "typeDefinitionId": "TYPE_ID",
    "mapping": [
      {
        "source": "subject",
        "target": "FIELD_CODE"
      }
    ]
  }
}

Ответ и ошибки

Успех: 201. Определение подключения.

{
  "data": {
    "id": "INTEGRATION_ID",
    "type": "inbound-webhook",
    "enabled": false
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Передать входящее событие

POST /api/v1/inbound/{integrationId}

Действие ключа: integrations:execute. Оно не заменяет права владельца на объекты и поля.

Тело зависит от config.mapping. Для object.update обязательны objectId, expectedRevision и хотя бы одно сопоставленное поле; для comment.add — objectId/body. Исполнение идёт с правами владельца ключа, не повышается до настроенного executionPrincipalId.

Параметры пути: integrationId. Тело: JSON; пример ниже показывает основные поля.

Поддерживает Idempotency-Key. См. безопасные повторы.

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

POST /api/v1/inbound/INTEGRATION_ID HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: example-operation-001

{
  "subject": "Новое обращение"
}

Ответ и ошибки

Успех: 201. Результат выбранной canonical команды.

{
  "data": {
    "id": "OBJECT_ID",
    "typeDefinitionId": "TYPE_ID",
    "revision": 1,
    "values": {
      "FIELD_CODE": "Значение"
    }
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Связанные статьи

• Обзор API
• Права доступа
• Интеграции