SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场sumsub-manage-webhooks

sumsub-manage-webhooks

安全与审计

查看项目

更新于 10-16 10:41

技能介绍

用途

本技能用于管理 Sumsub 的 clientWebhooks，即应用审核人相关事件订阅，例如 applicantReviewed、applicantPending、kytTxn 等。它支持列出、读取、创建和更新 ClientWebhook 事件订阅。

主要能力

  • 列出当前租户下的 Webhook 列表，返回 EntityResult<ClientWebhook>（{list: {items: [...] }}），服务端最多返回最早的 50 条。
  • 按 id 读取单个 Webhook，可用于从已知 id 解析名称，或在写入后验证结果。
  • 创建 Webhook，请求体不能包含 id，由服务端分配。
  • 更新已有 Webhook，按请求体中的 id 进行更新。

需要 manageClientSettings 权限。公开 API 没有 DELETE，也没有 /stats 端点；删除 Webhook 或查看每个 Webhook 的投递统计需使用 Sumsub 仪表板 UI。

使用方式

读取使用 /resources/api/clientWebhooks，写入使用 /resources/api/agent/clientWebhooks。认证方式为 App Token + secret，且仅限沙箱环境。技能通过 sumsub-api-auth 技能中描述的方式对每个请求签名。环境变量包括：

  • SUMSUB_APP_TOKEN：沙箱 App Token，以 sbx: 开头。
  • SUMSUB_SECRET_KEY：创建 Token 时一次性显示的配对密钥。
  • SUMSUB_BASE：可选，默认 https://api.sumsub.com。

辅助脚本会拒绝不以 sbx: 开头的 Token，除非设置 SUMSUB_ALLOW_PROD=1。

编排脚本 manage_webhooks.sh 提供以下子命令：

manage_webhooks.sh list                       # GET all webhooks (table summary; capped at 50)
manage_webhooks.sh list --json                # raw JSON of all webhooks
manage_webhooks.sh get <webhookId>            # one webhook (filtered from the list)
manage_webhooks.sh create <spec.json>         # POST without id  (compact spec → ClientWebhook)
manage_webhooks.sh update <spec.json>         # POST with id     (spec MUST contain id)

create 和 update 都会调用 build_webhook_payload.py 来扩展紧凑规格。

紧凑规格（create / update）

# Identity (omit on create; required on update)
id: 698bfc...                  # id from a previous list / create response

# Display + addressing
name: "Production webhook"     # required (no min length but the dashboard expects something)
description: "Sends KYC events to our backend"
target: "https://example.com/sumsub/webhook"   # required — destination URL (or slack / email / telegram address depending on targetType)
targetType: http               # http | email | slack | telegram   (default: http)

# Subscription
types:                         # required — event-type strings
  - applicantReviewed
  - applicantPending
  - applicantOnHold
  - applicantCreated
applicantType: individual      # individual | company   (omit to subscribe to both)
sourceKeys: []                 # optional — restrict to specific source keys

# Auth + delivery
secretKey: "..."               # HMAC secret used to sign payloads
signatureAlgorithm: HMAC_SHA256_HEX  # HMAC_SHA1_HEX | HMAC_SHA256_HEX | HMAC_SHA512_HEX  (default: SHA256)
headers:                       # optional extra HTTP headers added to each delivery
  - { key: "X-Source", value: "sumsub" }
  - { key: "Authorization", value: "Bearer ${MY_TOKEN}" }   # caller substitutes before sending

# Lifecycle flags
notResendFailedWebhooks: false # default false; true = no automatic retries on delivery failure

构建器会校验枚举（targetType、signatureAlgorithm、applicantType），拒绝空的 types，并包装 headers 使其 key/value 形状匹配 ClientWebhookHeader。未知键会透传（逃生通道）。

目标地址限制

Sumsub 从其自有基础设施投递 Webhook，因此目标 URL 必须能从公网解析并接受连接。常见问题：用户粘贴 http://localhost:3000/webhook（或 127.0.0.1、0.0.0.0、::1）。Sumsub 在创建时接受该 URL，但每次投递都会失败，且技能载荷构建器会直接拒绝这类目标。若用户提供类 localhost URL，应引导其通过公网隧道暴露本地服务器，例如使用 ngrok（brew install ngrok/ngrok/ngrok，首次需免费账户获取 auth token 并执行 ngrok config add-authtoken <TOKEN>，然后 ngrok http <port>）。免费版 ngrok 每次重启公网 URL 都会变化，需要重新更新 Webhook；付费保留域名或 --domain=<your-subdomain> 可保持稳定。替代方案包括 Cloudflare Tunnel、Tailscale Funnel、localtunnel。

事件类型

OpenAPI 中 types 为自由字符串数组。常见事件分组包括：

  • Applicant lifecycle：applicantCreated、applicantPrechecked、applicantPending、applicantReviewed、applicantOnHold、applicantActivated、applicantDeactivated、applicantReset、applicantLevelChanged、applicantTagsChanged、applicantPersonalInfoChanged、applicantDeleted、applicantPersonalDataDeleted。
  • Action workflow：applicantActionPending / applicantActionReviewed / applicantActionOnHold。
  • Workflow：applicantWorkflowCompleted（不是 applicantWorkflowRunCompleted）。
  • Video ident：videoIdentStatusChanged、videoIdentCompositionCompleted。
  • KYT（applicant 范围）：applicantKytTxnApproved / applicantKytTxnRejected / applicantKytTxnReviewed / applicantKytTxnDeleted / applicantKytTxnDataChanged / applicantKytTxnAwaitingUser / applicantKytOnHold。
  • KYT（case 范围）：kytCaseCreated / kytCaseStatusChanged / kytCaseReviewed（注意是 kytCaseStatusChanged，不是 kytCaseUpdated）。
  • AML case：amlCaseApproved / amlCaseRejected / amlCaseOnHold。
  • Travel Rule：travelRuleAction。
  • KYB：kybCompanyActivity。

技能会转发调用方写入的内容，不做客户端校验，因为 Sumsub 可能比本列表更快地新增事件。未知事件类型被服务端静默接受，但 Webhook 永远不会触发，因此拼写错误不会被 API 捕获。

输出

  • list：表格，含 id、name、target、disabled、types[]、applicantType、signatureAlgorithm、createdAt。
  • get：完整的单个 Webhook JSON（secretKey 在输出中被遮蔽）。
  • create / update：持久化的 ClientWebhook（创建时含服务端分配的 id）及一行摘要。

沙箱专属范围

由于本技能只接受沙箱 App Token，它创建或更新的所有 Webhook 都位于沙箱工作区。沙箱与生产是 Sumsub 侧相互独立的租户，没有“升级到生产”的路径。用户准备配置生产 Webhook 时：不要从本技能提供该操作，即使用户要求；不要索取或接受生产 App Token；告知用户生产 Webhook（目标 URL、签名密钥、事件订阅、自定义 headers）应由人工直接在 Sumsub 仪表板（Integrations → Webhooks，工作区开关切到 Production）配置。正确流程是：用本技能在沙箱中做原型，捕获用户想要的最终规格，然后作为纯文档交接给人工在生产中重建。

示例

  • examples/basic-http.json：最小 Webhook，HTTPS 端点、四个 applicant 生命周期事件、SHA-256 签名。
  • examples/with-headers-and-restrictions.json：广泛事件集，限定到特定 sourceKey，带自定义 HTTP headers。
  • examples/legacy-sha1.json：SHA1 签名 Webhook，供已校验 SHA1 的接收方使用。
  • examples/update-existing.json：与 basic 相同但设置了 id，演示更新路径。

相关参考

  • references/webhook-schema.md：完整 ClientWebhook schema、所有枚举、注意事项（secret 非只写、签名语义）。
  • Sumsub 文档：Webhook system、Webhook event types、Verify webhook signatures。