Back to Details

a1-yandex-kit-webhooks

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

A1 Yandex KIT — Webhooks

A1 Yandex KIT — Webhooks

Communication

沟通规范

Before producing any user-facing message, read and apply 
../a1-yandex-kit/references/merchant-communication.md
 completely.
Covers the Вебхуки tag of the Yandex KIT e-commerce API: subscribing HTTPS endpoints to order lifecycle notifications and managing those subscriptions.
Key facts:
  • Callback URLs must be HTTPS — plain 
    http://
    URLs are rejected.
  • Exactly three event types exist: 
    ORDER_STATUS_CHANGED
    , 
    ORDER_PAYMENT_STATUS_CHANGED
    and 
    ORDER_DELIVERY_STATUS_CHANGED
    .
  • ORDER_STATUS_CHANGED
    is being narrowed     (Yandex announced it; no cutoff date given): it will stop firing for the two receipt-technical statuses 
    CREATING_INITIAL_RECEIPT
    and 
    CREATING_FINAL_RECEIPTS
    . An integration triggered by those two events must move to 
    ORDER_PLACED
    and 
    COMPLETED
    respectively. An integration that merely stores the order's current status needs no change — both statuses stay in the 
    OrderStatus
    enum and in 
    GET /v1/orders/{order_id}
    ; only the callback disappears.
  • Creating a webhook (
    CreateWebhook
    ) returns a signing 
    secret
    that is shown only once — persist it immediately; it cannot be retrieved later (delete and recreate the webhook if lost).
  • The signature algorithm is not documented by Yandex. Use the secret to verify that incoming calls are authentic, but check the KIT community chat (https://t.me/+f9qV8snaY1pmM2Ji) or Yandex support for the current signing scheme before relying on any particular construction.
  • ValidateWebhook
    asks the API to POST a 
    WEBHOOK_VALIDATE
    event to your URL — use it to test reachability after deploying the receiver.
For authentication (
Authorization: Bearer <token>
), the base URL (
https://api.kit.yandex.net
, all paths under 
/v1/
), the 3 rps rate limit and the 
{code, message, trace_id}
error contract, see the 
a1-yandex-kit
skill.
在生成任何面向用户的消息之前，请完整阅读并应用
../a1-yandex-kit/references/merchant-communication.md
文档。
本文档涵盖Yandex KIT电商API的Вебхуки（Webhooks）标签内容：将HTTPS端点订阅至订单生命周期通知，并管理这些订阅。
关键要点：
  • 回调URL必须为HTTPS——普通
    http://
    URL会被拒绝。
  • 仅存在三种事件类型：
    ORDER_STATUS_CHANGED
    、
    ORDER_PAYMENT_STATUS_CHANGED
    和
    ORDER_DELIVERY_STATUS_CHANGED
    。
  • ORDER_STATUS_CHANGED
    的触发范围正在缩小    （Yandex已宣布，但未给出截止日期）：该事件将不再针对
    CREATING_INITIAL_RECEIPT
    和
    CREATING_FINAL_RECEIPTS
    这两个收据技术状态触发。依赖这两个事件的集成需分别迁移至
    ORDER_PLACED
    和
    COMPLETED
    事件。仅需存储订单当前状态的集成无需修改——这两个状态仍会保留在
    OrderStatus
    枚举和
    GET /v1/orders/{order_id}
    接口中，仅回调通知会取消。
  • 创建webhook（
    CreateWebhook
    ）会返回一个签名
    secret
    ，该密钥仅显示一次——请立即持久化存储；丢失后无法找回（若丢失需删除并重新创建webhook）。
  • Yandex未公开签名算法。可使用该密钥验证传入请求的真实性，但在依赖特定实现逻辑前，请查看KIT社区聊天群(https://t.me/+f9qV8snaY1pmM2Ji)或联系Yandex支持获取当前签名方案。
  • ValidateWebhook
    会请求API向你的URL发送
    WEBHOOK_VALIDATE
    事件——可在部署接收端后用它测试可达性。
关于认证方式（
Authorization: Bearer <token>
）、基础URL（
https://api.kit.yandex.net
，所有路径均在
/v1/
下）、3次/秒的速率限制以及
{code, message, trace_id}
错误约定，请查看
a1-yandex-kit
技能文档。

Workflow

操作流程

Run the bundled scripts from this skill's directory — they are self-contained (Node.js >= 20, builtins + a vendored validator, no 
npm install
, no network).
  1. Search for the operation you need:
    bash
    node scripts/search_docs.mjs "<query>" [--tag "<Тег>"] [--limit N]
    Matches operation ids, paths, tags and the Russian summaries/descriptions, e.g. 
    node scripts/search_docs.mjs "создать вебхук"
    .
  2. Inspect the full contract of one operation — path/query parameters plus the fully dereferenced request/response schemas:
    bash
    node scripts/search_docs.mjs --operation CreateWebhook
  3. Validate a drafted request body offline before sending anything:
    bash
    node scripts/validate.mjs --operation CreateWebhook --body '<json>'
# or: node scripts/validate.mjs --operation CreateWebhook --body-file body.json
    Prints 
    VALID
    (exit 0) or the list of schema violations (exit 1).
  4. Execute the operation:
    • prefer the matching 
      mcp-yandex-kit
      MCP tool from «Related MCP tools» below (e.g. 
      create_webhook
      , 
      validate_webhook
      );
    • any operation without a dedicated tool: the 
      kit_request
      MCP tool — it validates the body against the same schema before sending;
    • or plain HTTP: 
      curl -H "Authorization: Bearer $YANDEX_KIT_TOKEN" https://api.kit.yandex.net/v1/...
      (mind the 3 rps limit).
从本技能目录运行内置脚本——脚本为独立运行模式（需Node.js >= 20，仅依赖内置模块和本地验证器，无需
npm install
，无需网络）。
  1. 搜索所需操作：
    bash
    node scripts/search_docs.mjs "<查询关键词>" [--tag "<Тег>"] [--limit N]
    匹配操作ID、路径、标签以及俄文摘要/描述，例如：
    node scripts/search_docs.mjs "создать вебхук"
    。
  2. 查看单个操作的完整契约——包含路径/查询参数以及完全解引用的请求/响应 schema：
    bash
    node scripts/search_docs.mjs --operation CreateWebhook
  3. 离线验证拟发送的请求体，再执行发送：
    bash
    node scripts/validate.mjs --operation CreateWebhook --body '<json内容>'
# 或：node scripts/validate.mjs --operation CreateWebhook --body-file body.json
    验证通过会输出
    VALID
    （退出码0），否则输出schema违规列表（退出码1）。
  4. 执行操作：
    • 优先使用下方「相关MCP工具」中对应的
      mcp-yandex-kit
      工具（例如
      create_webhook
      、
      validate_webhook
      ）；
    • 无专用工具的操作：使用
      kit_request
      MCP工具——它会在发送前用相同schema验证请求体；
    • 或使用普通HTTP请求： 
      curl -H "Authorization: Bearer $YANDEX_KIT_TOKEN" https://api.kit.yandex.net/v1/...
      （注意3次/秒的速率限制）。

Endpoints (6 operations)

端点（6个操作）

Вебхуки

Вебхуки（Webhooks）

MethodPathOperationIdSummary (RU)
GET
/v1/webhooks
GetWebhooks
Получение списка вебхуков
POST
/v1/webhooks
CreateWebhook
Создание вебхука
POST
/v1/webhooks/{webhook_id}/validate
ValidateWebhook
Валидация вебхука
GET
/v1/webhooks/{webhook_id}
GetWebhookById
Получение вебхука по уникальному идентификатору
PATCH
/v1/webhooks/{webhook_id}
UpdateWebhook
Обновление вебхука
DELETE
/v1/webhooks/{webhook_id}
DeleteWebhook
Удаление вебхука
MethodPathOperationId摘要（中文）
GET
/v1/webhooks
GetWebhooks
获取webhook列表
POST
/v1/webhooks
CreateWebhook
创建webhook
POST
/v1/webhooks/{webhook_id}/validate
ValidateWebhook
验证webhook
GET
/v1/webhooks/{webhook_id}
GetWebhookById
根据唯一ID获取webhook
PATCH
/v1/webhooks/{webhook_id}
UpdateWebhook
更新webhook
DELETE
/v1/webhooks/{webhook_id}
DeleteWebhook
删除webhook

Related MCP tools

相关MCP工具

Curated 
mcp-yandex-kit
tools for these tags (the server also exposes the meta trio — 
search_operations
, 
get_operation_schema
, 
kit_request
— reaching all 161 operations):
  • list_webhooks
    — List all webhooks of the store (not paginated).
  • get_webhook
    — Get a single webhook by its ID (URL, subscribed events, status).
  • create_webhook
    — Create a new webhook.
  • update_webhook
    — Update an existing webhook: change url (HTTPS only), the subscribed events, or set deactivate=true to switch the webhook to INACTIVE.
  • delete_webhook
    — Permanently delete a webhook by its ID.
  • validate_webhook
    — Trigger webhook validation: the API sends a POST with event WEBHOOK_VALIDATE to the webhook URL.
针对这些标签整理的
mcp-yandex-kit
工具（服务器还暴露了元组工具——
search_operations
、
get_operation_schema
、
kit_request
——可覆盖全部161个操作）：
  • list_webhooks
    — 列出店铺的所有webhook（无分页）。
  • get_webhook
    — 根据ID获取单个webhook的信息（URL、订阅事件、状态）。
  • create_webhook
    — 创建新的webhook。
  • update_webhook
    — 更新现有webhook：修改URL（仅支持HTTPS）、订阅事件，或设置deactivate=true将webhook切换为INACTIVE状态。
  • delete_webhook
    — 根据ID永久删除webhook。
  • validate_webhook
    — 触发webhook验证：API会向webhook URL发送包含WEBHOOK_VALIDATE事件的POST请求。