Integration
Onfido, and what to do with a verdict that is neither yes nor no
Onfido performs document and biometric identity verification and returns a result your bot enforces. Its outcomes are not binary — a check can return clear, consider, or a rejection — and deciding what "consider" means for your access rules is the design decision that matters most.
Onfido integration: auth, limits and availability
- Auth model
- API key
- Report model
- One check yields multiple reports plus a derived overall outcome
- GCC availability
- Used by regulated GCC firms; confirm document coverage per market
- Data flow
- 5 hops, worker-mediated
As of 2025-10-01, Telegram Bot API 13.4
Why this integration exists
Onfido is the more common choice where the verification requirement comes from a financial services or regulated-firm context rather than from crypto specifically, and its model reflects that. Rather than a single verdict, a check produces reports — document authenticity, facial similarity, watchlist screening — each with its own result, and an overall outcome derived from them.
That granularity is genuinely useful and it forces a decision most integrations would rather avoid. Alongside clear and rejected there is consider, which means the automated checks found something worth a human looking at. It is not a failure. Treating it as one refuses real customers whose documents were merely photographed badly; treating it as a pass defeats the point of running the check.
The correct answer is a review queue with a named owner and a target response time, agreed before launch. That is an operational commitment rather than an engineering one, and a project that ships without it will quietly resolve consider as either always-approve or always-reject within a fortnight — whichever produces fewer complaints from whoever shouts loudest.
How the data actually moves
An API token held as a Worker secret, with a region-specific base URL that must match the region the account was created in. Webhooks are signed and the signature is verified against the raw body before the payload is trusted, since an unverified endpoint accepts fabricated clear verdicts.
Auth model: API key
Their limits, and what they mean for you
A check produces multiple reports, each with its own result, plus a derived overall outcome.
Access rules can be written against individual reports rather than the summary. That granularity is the reason to choose Onfido and is wasted if only the overall result is read.
API base URLs are region-specific and a token is not valid across regions.
Region is explicit configuration validated at startup. As with several providers, a mismatch presents as an authentication error and sends people to check credentials that were fine.
Workflows are versioned, and changing one affects checks created afterwards.
A workflow change is a deployment-shaped event. Two applicants verified a day apart can be assessed against different rules, which matters when someone asks why.
Webhook events are signed and delivered at least once.
Signature verification against the raw body, and idempotent handling on the check id. Both are small and both are routinely skipped.
How it fails, and what happens when it does
A consider outcome arrives and nobody owns the review queue.
The applicant waits indefinitely. This is the most common operational failure with Onfido and it is a staffing decision rather than a technical one, which is why it is agreed before launch.
A poor photograph produces a consider on document authenticity.
The applicant is offered a retry with specific guidance rather than being rejected. A meaningful share of considers are lighting and focus rather than fraud.
The webhook signature check fails after a proxy modifies the body.
Verification runs against the raw bytes received. Any middleware that reformats JSON breaks it, which is worth knowing before adding one.
A check completes but the webhook is lost.
A reconciliation job polls for checks still pending past a threshold. A completed verification nobody acts on is indistinguishable to the applicant from a rejection.
Availability in the UAE and the wider GCC
Global
Broad document coverage with region-specific hosting. Confirm coverage for the nationalities your users actually hold rather than for the country you operate in.
United Arab Emirates and GCC
Used by regulated firms in the region. Your obligations come from your own licence; the provider supplies evidence rather than discharging them.
Financial services context
Where Onfido is usually preferred over crypto-oriented providers, largely because of the report granularity and watchlist screening.
Data residency
Region selection affects where identity data is held. Choose the region before creating the account, since it is not something to change afterwards.
When not to use this integration
- Nobody will own the review queue. Consider outcomes are a normal part of the model and an unowned queue means applicants wait forever.
- You only ever read the overall outcome. Then you are paying for report granularity you discard, and a simpler provider would serve you.
- Your requirement is document collection rather than identity verification. That is a different and much cheaper build.
- You have not chosen a data region. It cannot be changed after account creation and is easier to decide than to migrate.
What it runs on
| Component | Version | Why |
|---|---|---|
| Cloudflare Workers | current | Applicant and check creation, signature verification, webhook handling. |
| Cloudflare D1 | current | Outcomes per report, review queue state and the audit trail. |
| Zod | 4.4 | Validation of webhook payloads after signature verification. |
| grammY | 1.45 | Applicant conversation, retry guidance and admission. |
Questions that come up during scoping
What does a consider outcome mean, and what should we do with it?
That automated checks found something worth a human looking at. It is not a failure. It needs a review queue with a named owner and a target response time agreed before launch, or the integration will quietly settle into always-approve or always-reject within a fortnight.
How is this different from Sumsub?
Onfido returns granular per-report results and is more common in a financial services context; Sumsub is more common among crypto businesses and has broader coverage in that market. Both have workable webhook models and the choice is usually driven by your sector and your existing contracts.
Why do checks fail authentication despite a valid token?
Region mismatch. Base URLs are region-specific and tokens are not portable, and the error presents as authentication rather than routing. Startup validation turns a day of confusion into a deploy-time message.
Should a bad photograph be rejected?
No. A meaningful share of consider outcomes are lighting and focus rather than fraud, so the applicant is offered a retry with specific guidance. Rejecting them loses real customers for a reason that is easy to fix.
What happens if a workflow is changed mid-project?
Checks created afterwards are assessed against the new version, so two applicants a day apart can face different rules. It is treated as a deployment-shaped event because the difference matters when somebody asks why one was admitted.
Do we need watchlist screening?
That is a compliance question for your counsel rather than a configuration preference. It is available as part of the check; whether you are required to run it depends on your licence and your activity.
Related reading
For a crypto-oriented alternative with broader coverage in that market, see the Sumsub integration.
Enforcement and the evidence trail are covered by the KYC-gated access build.
Where the requirement is gathering files rather than verifying identity, the cheaper build is the document collection build.
Other providers a regulated flow commonly touches are covered across the full integration list.