DEVELOPER PLATFORM · v1

API, с которым удобно работать

CRM, кампании, аналитика и интеграции. Точные контракты, понятные примеры и подписанные вебхуки.

Private preview: API доступен с проектным ключом. Публичные SLA и сроки поддержки ещё не установлены.

PUT

Настроить исходящий Webhook API

/api/v1/developer/integrations/{installationId}/outbound-webhook

Создаёт или обновляет endpoint и allowlist событий. Новая signing secret возвращается только при первом создании и только в первом выполнении Idempotency-Key; безопасный replay её не раскрывает. Потерянную secret замените отдельной rotate-командой.

Право доступаintegrations.webhooks.write

Authorization: Bearer YOUR_PROJECT_TOKEN

Параметры

installationIdобязательно · path: stringminLength: 1 · maxLength: 160
JSON Schema
{ "type": "string", "minLength": 1, "maxLength": 160 }
idempotency-keyобязательно · header: stringpattern: "^[\\x21-\\x7E]+$" · minLength: 1 · maxLength: 160
JSON Schema
{ "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[\\x21-\\x7E]+$" }

Тело запроса

application/json

object

endpointUrlобязательно: stringformat: "uri" · maxLength: 2048
eventTypesобязательно: arrayminItems: 1 · maxItems: 20
Вложенная схема
arrayminItems: 1 · maxItems: 20
stringenum: ["crm.deal.created.v1","crm.deal.updated.v1","crm.deal.stage_changed.v1","crm.task.created.v1","crm.task.completed.v1"]
JSON Schema
{ "type": "string", "enum": [ "crm.deal.created.v1", "crm.deal.updated.v1", "crm.deal.stage_changed.v1", "crm.task.created.v1", "crm.task.completed.v1" ] }
JSON Schema
{ "type": "array", "items": { "type": "string", "enum": [ "crm.deal.created.v1", "crm.deal.updated.v1", "crm.deal.stage_changed.v1", "crm.task.created.v1", "crm.task.completed.v1" ] }, "minItems": 1, "maxItems": 20 }
expectedVersionобязательно: integer | nullexclusiveMinimum: 0

JSON Schema

{
  "type": "object",
  "properties": {
    "endpointUrl": {
      "type": "string",
      "maxLength": 2048,
      "format": "uri"
    },
    "eventTypes": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "crm.deal.created.v1",
          "crm.deal.updated.v1",
          "crm.deal.stage_changed.v1",
          "crm.task.created.v1",
          "crm.task.completed.v1"
        ]
      },
      "minItems": 1,
      "maxItems": 20
    },
    "expectedVersion": {
      "type": [
        "integer",
        "null"
      ],
      "exclusiveMinimum": 0
    }
  },
  "required": [
    "endpointUrl",
    "eventTypes",
    "expectedVersion"
  ],
  "additionalProperties": false
}

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

curl --request PUT   'https://YOUR_NOVA_HOST/api/v1/developer/integrations/INSTALLATION_ID/outbound-webhook'   --header 'Authorization: Bearer YOUR_PROJECT_TOKEN'   --header 'Idempotency-Key: YOUR_UNIQUE_COMMAND_ID'   --header 'Content-Type: application/json'   --data '{"endpointUrl":"https://hooks.example.com/nova","eventTypes":["crm.deal.created.v1"],"expectedVersion":null}'

Ответы

200 Configured outbound webhook receipt

application/json

object

resourceIdобязательно: stringminLength: 1 · maxLength: 160
changedобязательно: boolean
signingSecret: string

JSON Schema

{
  "type": "object",
  "properties": {
    "resourceId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 160
    },
    "changed": {
      "type": "boolean"
    },
    "signingSecret": {
      "type": "string"
    }
  },
  "required": [
    "resourceId",
    "changed"
  ],
  "additionalProperties": false,
  "$ref": "#/components/schemas/DeveloperOutboundWebhookMutationResponse"
}

400 Invalid outbound webhook reference

application/problem+json

object

type: stringformat: "uri" · default: "about:blank"
titleобязательно: string
statusобязательно: integerminimum: 100 · maximum: 599
detail: string
instance: string
errors: object

JSON Schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri",
      "default": "about:blank"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer",
      "minimum": 100,
      "maximum": 599
    },
    "detail": {
      "type": "string"
    },
    "instance": {
      "type": "string"
    },
    "errors": {
      "type": "object",
      "additionalProperties": {}
    }
  },
  "required": [
    "title",
    "status"
  ]
}

401 Invalid developer credential

application/problem+json

object

type: stringformat: "uri" · default: "about:blank"
titleобязательно: string
statusобязательно: integerminimum: 100 · maximum: 599
detail: string
instance: string
errors: object

JSON Schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri",
      "default": "about:blank"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer",
      "minimum": 100,
      "maximum": 599
    },
    "detail": {
      "type": "string"
    },
    "instance": {
      "type": "string"
    },
    "errors": {
      "type": "object",
      "additionalProperties": {}
    }
  },
  "required": [
    "title",
    "status"
  ]
}

403 Outbound webhook access unavailable

application/problem+json

object

type: stringformat: "uri" · default: "about:blank"
titleобязательно: string
statusобязательно: integerminimum: 100 · maximum: 599
detail: string
instance: string
errors: object

JSON Schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri",
      "default": "about:blank"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer",
      "minimum": 100,
      "maximum": 599
    },
    "detail": {
      "type": "string"
    },
    "instance": {
      "type": "string"
    },
    "errors": {
      "type": "object",
      "additionalProperties": {}
    }
  },
  "required": [
    "title",
    "status"
  ]
}

404 Outbound webhook installation not found

application/problem+json

object

type: stringformat: "uri" · default: "about:blank"
titleобязательно: string
statusобязательно: integerminimum: 100 · maximum: 599
detail: string
instance: string
errors: object

JSON Schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri",
      "default": "about:blank"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer",
      "minimum": 100,
      "maximum": 599
    },
    "detail": {
      "type": "string"
    },
    "instance": {
      "type": "string"
    },
    "errors": {
      "type": "object",
      "additionalProperties": {}
    }
  },
  "required": [
    "title",
    "status"
  ]
}

409 Idempotency, version or webhook state conflict

application/problem+json

object

type: stringformat: "uri" · default: "about:blank"
titleобязательно: string
statusобязательно: integerminimum: 100 · maximum: 599
detail: string
instance: string
errors: object

JSON Schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri",
      "default": "about:blank"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer",
      "minimum": 100,
      "maximum": 599
    },
    "detail": {
      "type": "string"
    },
    "instance": {
      "type": "string"
    },
    "errors": {
      "type": "object",
      "additionalProperties": {}
    }
  },
  "required": [
    "title",
    "status"
  ]
}

429 Developer API rate limit exceeded

application/problem+json

object

type: stringformat: "uri" · default: "about:blank"
titleобязательно: string
statusобязательно: integerminimum: 100 · maximum: 599
detail: string
instance: string
errors: object

JSON Schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri",
      "default": "about:blank"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer",
      "minimum": 100,
      "maximum": 599
    },
    "detail": {
      "type": "string"
    },
    "instance": {
      "type": "string"
    },
    "errors": {
      "type": "object",
      "additionalProperties": {}
    }
  },
  "required": [
    "title",
    "status"
  ]
}

503 Developer API rate limiter unavailable

application/problem+json

object

type: stringformat: "uri" · default: "about:blank"
titleобязательно: string
statusобязательно: integerminimum: 100 · maximum: 599
detail: string
instance: string
errors: object

JSON Schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri",
      "default": "about:blank"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer",
      "minimum": 100,
      "maximum": 599
    },
    "detail": {
      "type": "string"
    },
    "instance": {
      "type": "string"
    },
    "errors": {
      "type": "object",
      "additionalProperties": {}
    }
  },
  "required": [
    "title",
    "status"
  ]
}