
sumsub-manage-webhooks
Manage Sumsub clientWebhooks (event subscriptions for applicantReviewed / applicantPending / kytTxn / etc.) — reads via /resources/api/clientWebhooks, writes via /resources/api/agent/clientWebhooks. Sandbox only — production webhooks must be created by a human directly in the Sumsub dashboard. TRIGGER when the user asks to "list / retrieve / show webhooks", "create / add / register a webhook", or "update / edit / change a webhook target / event list / secret / signature algorithm" against their sandbox tenant. SKIP for production webhook setup (refer the user to the dashboard), for unrelated webhook surfaces (Stripe / videoIdent / Fireblocks / NFC / partner-specific receive paths under /resources/webhooks/...), for testing one-off delivery (use the inspectionCallbacks/testWebhook endpoint directly), and for KYT-only webhook routing (that's managed in the Sumsub dashboard's KYT section). The public API does not expose delete or per-webhook delivery stats — for those, refer
- Installs
- 1.2K
- Last 24h
- +16
- Trending rank
- #6832
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/sumsub/agent-skills --skill sumsub-manage-webhooks- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads sumsub-manage-webhooks automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Sumsub — Manage Client Webhooks
Lists, retrieves, creates, and updates ClientWebhook
event subscriptions. Reads use /resources/api/clientWebhooks; writes use
/resources/api/agent/clientWebhooks.
Endpoints
| Verb | Path | Purpose |
|---|---|---|
GET | /resources/api/clientWebhooks | List webhooks on the tenant. Returns EntityResult<ClientWebhook> ({list: {items: [...] }}). Capped at the oldest 50 server-side (getOldest50). |
GET | /resources/api/clientWebhooks/{id} | Read one webhook by id. Use this to resolve a name from a known id, or to verify what landed after a write. |
POST | /resources/api/agent/clientWebhooks | Create. Body must NOT include id — server assigns it. (The model layer still does an internal upsert, but the request DTO is ClientWebhookCreateRequest without id.) |
PATCH | /resources/api/agent/clientWebhooks | Update an existing webhook (by id in body). DTO is ClientWebhookUpdateRequest. |
Permission required: manageClientSettings.
There is no DELETE and no /stats endpoint on the public API —
use the Sumsub dashboard UI when you need to delete a webhook or view
per-webhook delivery stats.
Auth — App Token + secret (sandbox only)
This skill talks to the public Sumsub API and signs each request per
the authentication reference.
The full how-it-works writeup lives in the sumsub-api-auth
skill — read it if you hit 401 Invalid signature.
⚠️ Sandbox tokens only. Do not accept or use a production App Token here. If the user offers one, refuse and ask them to generate a sandbox pair at https://cockpit.sumsub.com/checkus/home?sbx=true (Connect Sumsub to your AI agent -> Build & configure -> Generate token). Token + secret are shown once — copy both before closing the dialog. The helper script enforces this — it rejects tokens that don't start with
sbx:unlessSUMSUB_ALLOW_PROD=1is set.
| Var | Example |
|---|---|
SUMSUB_APP_TOKEN | sbx:... — sandbox App Token from the dashboard. |
SUMSUB_SECRET_KEY | The paired secret shown once at token creation. |
SUMSUB_BASE | Optional. Defaults to https://api.sumsub.com. |
If the user has already supplied credentials in conversation, reuse them; otherwise ask once before running. Never echo the secret back.
Sandbox-only scope — production webhooks must be created by a human
Because this skill only accepts sandbox App Tokens, every webhook it creates or updates lives in the sandbox workspace. Sandbox and production are separate tenants on Sumsub's side — there is no "promote to prod" path, and re-running this skill with a production token is not the right way to set up a real webhook.
When the user is ready to wire up a production webhook:
- Do not offer to do it from this skill, even if the user asks.
- Do not ask for or accept a production App Token (the script will refuse
it without
SUMSUB_ALLOW_PROD=1, and you should not suggest that override). - Tell the user that the production webhook — target URL, signing secret, event subscription, custom headers — should be configured by a human directly in the Sumsub dashboard (Integrations → Webhooks, with the workspace toggle on Production). Setting up a production webhook is a security-sensitive operation (the signing secret authenticates real PII deliveries) and the audit trail should attribute it to a person.
- The right workflow is: use this skill to prototype against sandbox, capture the final spec the user wants (event list, headers, signature algorithm), then hand that spec off as plain documentation so a human can recreate it in production.
Subcommands
manage_webhooks.sh is the orchestrator:
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 and update both call build_webhook_payload.py to expand the compact spec.
Before submitting: target must be publicly reachable
Sumsub delivers webhooks from its own infrastructure, so the target URL has to resolve and accept connections from the public internet. Common gotcha: users paste http://localhost:3000/webhook (or 127.0.0.1, 0.0.0.0, ::1) while developing locally. Sumsub accepts the URL at creation time but every delivery will fail — and targets like these are rejected by the skill's payload builder up front.
If the user supplies a localhost-ish URL, don't submit it. Instead, walk them through exposing the local server through a public tunnel before creating the webhook:
- Suggest ngrok (the most common choice). On macOS:
brew install ngrok/ngrok/ngrok. Other platforms: download from the link. First-time users need a free ngrok account to grab an auth token, thenngrok config add-authtoken <TOKEN>once. - Ask which port their local webhook receiver listens on (typically 3000 / 8080 / 4000).
- Have them run
ngrok http <port>in a separate terminal and keep it open. - ngrok prints a
Forwarding https://<random>.ngrok-free.app -> http://localhost:<port>line. Thehttps://...ngrok-free.apppart is the public URL. - Append the receiver's webhook path (e.g.
/webhook,/sumsub) and use the full URL astarget. Then re-run thecreatesubcommand.
Heads-up to mention: on the free ngrok plan the public URL changes every time ngrok restarts — the webhook will need to be re-updated (POST with the existing id and the new target) each session. A reserved domain (paid) or --domain=<your-subdomain> keeps it stable. Alternatives if the user prefers: Cloudflare Tunnel (cloudflared tunnel), Tailscale Funnel, localtunnel — same idea, same procedure.
Compact spec for 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 (see "Event types" below)
- 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
The builder validates enums (targetType, signatureAlgorithm, applicantType), rejects empty types, and wraps headers so that the key/value shape matches ClientWebhookHeader. Unknown keys pass through (escape hatch).
Event types (types[])
The OpenAPI keeps types as a free-form string[]. The names below cover
the commonly-emitted Sumsub events. Unknown event types are silently
accepted server-side and the webhook simply never fires — so typos are not
caught by the API.
| Group | Event type | When it fires |
|---|---|---|
| Applicant lifecycle | applicantCreated | New applicant created |
applicantPrechecked | Pre-screen complete | |
applicantPending | Submitted for review | |
applicantReviewed | Final review answer (GREEN / RED) reached | |
applicantOnHold | Review held / paused | |
applicantActivated | Applicant activated | |
applicantDeactivated | Applicant deactivated | |
applicantReset | Verification reset (retry) | |
applicantLevelChanged | Level reassigned | |
applicantTagsChanged | Tags added/removed | |
applicantPersonalInfoChanged | Personal info edited | |
applicantDeleted | Applicant deleted | |
applicantPersonalDataDeleted | GDPR personal-data erasure executed | |
| Action workflow | applicantActionPending / applicantActionReviewed / applicantActionOnHold | Action-flow events |
| Workflow | applicantWorkflowCompleted | Workflow run finished (not applicantWorkflowRunCompleted) |
| Video ident | videoIdentStatusChanged | Live status update |
videoIdentCompositionCompleted | Recording assembly finished | |
| KYT (applicant-scoped) | applicantKytTxnApproved / applicantKytTxnRejected / applicantKytTxnReviewed / applicantKytTxnDeleted / applicantKytTxnDataChanged / applicantKytTxnAwaitingUser / applicantKytOnHold | Per-applicant transaction-monitoring events |
| KYT (case-scoped) | kytCaseCreated / kytCaseStatusChanged / kytCaseReviewed | KYT case-management events (note: it's kytCaseStatusChanged, not kytCaseUpdated) |
| AML case | amlCaseApproved / amlCaseRejected / amlCaseOnHold | AML-case disposition events |
| Travel Rule | travelRuleAction | Travel-rule lifecycle events |
| KYB | kybCompanyActivity | KYB ongoing-monitoring events |
The skill forwards whatever the caller writes — no client-side validation, since Sumsub may add events faster than this list updates.
Outputs
list— table withid,name,target,disabled,types[],applicantType,signatureAlgorithm,createdAt.get— the full single webhook JSON (withsecretKeyredacted in the output as a defensive measure).create/update— the persistedClientWebhook(with server-assignedidon create) and a one-line summary.
Worked examples
examples/basic-http.json— minimal webhook: HTTPS endpoint, four applicant-lifecycle events, SHA-256 signing.examples/with-headers-and-restrictions.json— broad event set scoped to a specificsourceKey, with custom HTTP headers.examples/legacy-sha1.json— SHA1-signed webhook, for receivers that already verify SHA1.examples/update-existing.json— same as basic but withidset, demonstrating the update path.
See also
references/webhook-schema.md— fullClientWebhookschema, all enums, gotchas (secret not write-only, signing semantics).- Sumsub docs: Webhook system, Webhook event types, Verify webhook signatures.
FAQ
What does the sumsub-manage-webhooks skill do?
Manage Sumsub clientWebhooks (event subscriptions for applicantReviewed / applicantPending / kytTxn / etc.) — reads via /resources/api/clientWebhooks, writes via /resources/api/agent/clientWebhooks. Sandbox only — production webhooks must be created by a human directly in the Sumsub dashboard. TRIGGER when the user asks to "list / retrieve / show webhooks", "create / add / register a webhook", or "update / edit / change a webhook target / event list / secret / signature algorithm" against their sandbox tenant. SKIP for production webhook setup (refer the user to the dashboard), for unrelated webhook surfaces (Stripe / videoIdent / Fireblocks / NFC / partner-specific receive paths under /resources/webhooks/...), for testing one-off delivery (use the inspectionCallbacks/testWebhook endpoint directly), and for KYT-only webhook routing (that's managed in the Sumsub dashboard's KYT section). The public API does not expose delete or per-webhook delivery stats — for those, refer
How do I install sumsub-manage-webhooks?
Run npx skills add https://github.com/sumsub/agent-skills --skill sumsub-manage-webhooks in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/sumsub-manage-webhooks/ (personal) or .claude/skills/sumsub-manage-webhooks/ (project).
Which AI agents can use sumsub-manage-webhooks?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is sumsub-manage-webhooks safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains sumsub-manage-webhooks?
It is published by sumsub in sumsub/agent-skills. It has 1,189 recorded installs.
More from sumsub/agent-skills
sumsub-api-auth
sumsub/agent-skills
Authenticate to the Sumsub API with an App Token + secret key (HMAC-SHA256 request signing). TRIGGER when the user asks to "call / sign / authenticate Sumsub API requests", debugs 401 Unauthorized / signature errors against api.sumsub.com, or needs a working request example with X-App-Token / X-App-Access-Sig / X-App-Access-Ts headers. SKIP only when a more specific skill in this repo (questionnaire/level/workflow/POA-preset/generic) already covers the user's actual task — those skills sign requests the same way and only need this one for auth deep dives.
sumsub-api-generic
sumsub/agent-skills
Catch-all fallback for any Sumsub API task that does NOT match a more specific skill (e.g. create-sumsub-level, sumsub-create-questionnaire, sumsub-api-auth). TRIGGER when the user wants to call, inspect, or debug a Sumsub API endpoint not otherwise covered — fetching applicants, listing levels, reviewing AML hits, exporting data, generating SDK tokens, anything against api.sumsub.com. The procedure — locate the right endpoint in the OpenAPI schema, read its request/response shape, build the payload, sign with App Token, and validate. SKIP whenever a narrower Sumsub skill already covers the request.
sumsub-check-skills-version
sumsub/agent-skills
Verify that the locally installed Sumsub agent-skills package is compatible with the published version before doing any Sumsub work. TRIGGER at the start of any task that touches Sumsub — Sumsub Dev MCP tools (mcpSumsubDev), KYC/AML workflows, applicants, checks, transactions, verification levels, verification links, questionnaires, fraud network, VASP lists, or anything Sumsub-related — so the user is warned before a stale skills package produces wrong results. Also use this skill when the user explicitly asks "are my Sumsub skills up to date / current", "is there a newer version of the Sumsub skills", or similar. Skip the actual update (the user runs npx skills add sumsub/agent-skills --all themselves) and skip any other Sumsub API or entity task — those have their own skills.
sumsub-create-poa-preset
sumsub/agent-skills
Create or update a Sumsub Proof-of-Address (POA) preset. POST /resources/api/agent/poaStepSettings to create new, PATCH same path to update (id in body), GET /resources/api/agent/poaStepSettings/{id} to read one back. TRIGGER when the user asks to "create / add / build / configure / update / edit a POA preset" or "PoA step settings", configure which proof-of-address document types are accepted (utility bills, bank statements, tax bills, etc.), set validity periods per provider type, enable POI-as-POA (accept identity doc as proof of address), tune the cross-validator (name/address fuzzy match between POI and POA), or add per-country POA overrides. SKIP for attaching a preset to a level (set poaStepSettingsId on the level instead, via sumsub-create-level), or for non-POA presets (cross-check presets, permission presets, etc.).
sumsub-integrate-websdk
sumsub/agent-skills
End-to-end recipe for adding Sumsub KYC to a website or web app via the Sumsub WebSDK. TRIGGER when the user asks to "integrate / embed / add Sumsub", "show the KYC widget", "add WebSDK", "verify users with Sumsub on the frontend", supplies an existing levelName they want to plug into a page, or asks how to wire up access tokens / lifecycle events / webhooks for Sumsub verification in an arbitrary project. Covers the whole loop — level setup, server-side access-token signing, snsWebSdk init (vanilla canonical, React recipe), client lifecycle events, token refresh, source-of-truth via webhooks + applicant GET, sandbox testing, go-live checklist. SKIP for building the level/questionnaire/POA-preset payload itself (use the sibling skills), or for backend-only API calls with no frontend (use sumsub-api-generic).
sumsub-create-level
sumsub/agent-skills
Create or update a Sumsub applicant level. POST /resources/applicants/-/levels to create new, PATCH same path to update (id in body), GET /resources/applicants/-/levels/{id} to read one back. TRIGGER when the user asks to "create / add / build / update / edit a Sumsub level", supplies a list of required steps for an applicant flow (identity / selfie / proof-of-residence / questionnaire / payment methods / email or phone verification / KYB / e-sign), or wants a level wired to a specific questionnaireDefId. SKIP for other Sumsub entities (questionnaires, workflows, applicants) or for one-off subsetting tweaks not covered by the compact spec (use sumsub-api-generic for those).
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.