Integration

Sumsub, and why the documents must never reach you

Sumsub performs identity verification and returns a verdict your bot enforces. The correct architecture keeps identity documents entirely inside Sumsub — your Worker receives a decision and a country determination, never a passport scan. That keeps your data protection obligations proportionate to what you actually need.

Sumsub integration: auth, limits and availability

Auth model: HMAC-signed
Verdicts: Revisable after first issue — the applicant lifecycle is not terminal
GCC availability: Widely used by VARA-regulated businesses in the UAE
Data flow: 5 hops, worker-mediated

As of 2025-10-01, Telegram Bot API 13.4

Why this integration exists

A regulated crypto business gating a Telegram community needs to establish who is in the room and where they are resident. Doing that credibly means a licensed provider, because a form where a user asserts their own country is a record of a claim rather than evidence of anything, and a regulator asking how residency was established will say so.

The temptation once a provider is in place is to collect the documents yourself and pass them along, usually because it feels like more control. It is the wrong instinct. The moment a passport scan touches your infrastructure you have acquired a data protection obligation, a retention policy, an encryption-at-rest requirement and a breach exposure — all for information you do not need and cannot act on. Sumsub hosts the capture flow; your side receives a verdict.

What your side does need is the enforcement and the evidence trail. Which decision was made, when, by which provider, on what basis, and what access followed from it. That is the part a bot is genuinely good at and the part that gets skipped, because it is invisible until somebody asks — at which point it is the only thing that matters.

How the data actually moves

Documents travel between the applicant and Sumsub only. The Worker sees an applicant id, a verdict and a country determination.

API requests are signed with an app token and a secret key using an HMAC over the request, and inbound webhooks carry their own signature which must be verified before the payload is trusted. An unverified webhook endpoint accepts fabricated approval events, which in this context means admitting anyone who can find the URL.

Auth model: HMAC-signed requests

Their limits, and what they mean for you

Applicants move through a defined lifecycle, and a verdict can be revised after it is first issued.

A single approval webhook is not the end of the story. The bot handles later status changes, because an approval reversed after admission leaves someone inside who should not be.

Webhook payloads are signed and must be verified against the raw request body.

Parsing the body before verification breaks the signature. It presents as intermittent verification failure and is entirely deterministic once the ordering is examined.

Verification levels are configured in Sumsub, not in your code.

Changing what is checked is a console change with immediate effect on live traffic. It is worth treating as a deployment rather than as a setting somebody can adjust on a Friday.

Manual review introduces latency measured in minutes to hours.

A meaningful share of applicants will not be decided instantly. The waiting state is a real part of the user experience and is where most abandonment happens.

How it fails, and what happens when it does

An applicant is approved and then reversed on later review.

The bot removes access on the reversal. Treating the first approval as final leaves someone admitted whose verification no longer stands, which is exactly the gap an audit looks for.

A webhook is delivered twice for the same status change.

Handlers are idempotent on applicant id and status. Duplicate delivery is normal and double-processing an admission is harmless while double-processing a removal is confusing.

An applicant abandons midway through the hosted flow.

They sit in a pending state indefinitely unless prompted. A single reminder after a delay recovers a noticeable share; more than one reads as pressure about a passport, which people resent.

The webhook never arrives because of a transient fault.

A reconciliation job polls applicant status for anything pending past a threshold. Without it, a verified applicant waits forever for an admission nobody is going to grant.

Availability in the UAE and the wider GCC

Global

Broad document and country coverage, which is the main reason crypto businesses choose it. Confirm coverage for the specific nationalities your community actually holds.

United Arab Emirates

Widely used by VARA-regulated businesses. Your obligations are set by your own licence rather than by the provider, and the provider does not discharge them.

Sanctions and PEP screening

Available as part of the verification levels. Whether you are required to run it is a compliance question for your counsel, not a configuration preference.

Data residency

Sumsub holds the documents in its own infrastructure. Where a regulator requires local residency of identity data, that is a conversation to have before selecting a provider.

When not to use this integration

Your community carries no regulated content. Identity verification on a general discussion group costs you the community and buys nothing.
You intend to store the documents yourself. That acquires an obligation you do not need for information you cannot act on.
You have no compliance position to enforce. The bot enforces a rule you defined; it does not tell you what the rule should be.
You need instant admission for everyone. Manual review is part of the model and a share of applicants will wait.

What it runs on

Component	Version	Why
Cloudflare Workers	current	Applicant creation, signature verification and webhook handling.
Cloudflare D1	current	Verdicts, jurisdiction determinations, admissions and the audit trail.
Zod	4.4	Validation of webhook payloads after signature verification.
grammY	1.45	Join request handling and the applicant-facing conversation.

Questions that come up during scoping

Do passport scans pass through our systems?

No, and they should not. The applicant completes verification in Sumsub's hosted flow and your Worker receives an applicant id, a verdict and a country determination. That keeps your data protection obligations proportionate to what you actually use.

Is one approval webhook enough?

No. Verdicts can be revised after they are first issued, so the bot handles later status changes and removes access on a reversal. Treating the first approval as final leaves people admitted whose verification no longer stands.

Why does signature verification fail intermittently?

Almost always because the request body was parsed before verification. The signature is computed over the raw bytes, so any re-serialisation breaks it — it looks random and is completely deterministic.

How is residency established?

By Sumsub, from verified identity documents. Not from IP address and not from phone country code, neither of which would survive a question about how you determined it.

What happens to applicants who start and do not finish?

They stay pending and get one reminder after a delay. More than one reads as pressure about handing over a passport, which people resent and which does not improve completion.

Does using Sumsub make us compliant?

No. It performs verification and gives you evidence. Whether your rule is the right one, and whether your underlying activity is licensed, are questions for your counsel and sit entirely upstream of the integration.