Integration
Link screening, and the phishing domain registered an hour ago
A urlscan.io integration screens links posted in a Telegram community by submitting them for analysis and reading the verdict. Feed-based screening always trails fresh phishing, so heuristics run alongside it, and submissions must never leak private URLs into a public scan archive.
urlscan.io integration: auth, limits and availability
- Auth model
- API key
- Scan time
- Seconds — the page is actually rendered
- GCC availability
- Public service, no regional restriction
- Data flow
- 5 hops, worker-mediated
As of 2025-10-01, Telegram Bot API 13.4
Why this integration exists
Link screening in a crypto community is a race the defender is structurally behind in. Phishing domains are registered hours before use and retired within days, so any reputation feed is looking for something it has not seen. A screening system built purely on known-bad lists catches yesterday's campaign and misses today's, which is the one that matters.
urlscan is useful because it does more than look up a reputation. It renders the page and reports what it saw — the domains contacted, the resources loaded, whether the page resembles a known brand. That behavioural signal catches a wallet-drainer on a domain registered an hour ago in a way a reputation list cannot, because the page behaves like every other one in the campaign even though the domain is new.
The constraint that requires care is visibility. urlscan submissions can be public, and a public scan is archived and searchable. A link containing a session token, an invite or an internal address must not be submitted publicly, and the distinction between a public community link and something a member pasted carelessly is not always obvious in advance. Submitting unlisted by default is the only safe posture.
How the data actually moves
An API key held as a Worker secret, used for submission and for retrieving results. The visibility setting on every submission is explicit rather than defaulted, because the default determines whether a URL enters a public, permanently searchable archive.
Auth model: API key
Their limits, and what they mean for you
A scan takes seconds to complete, since the page is actually rendered.
Screening is not instantaneous. Heuristics act immediately and the scan verdict follows, which is why both run rather than one.
Submissions can be public, unlisted or private, and public scans are permanently searchable.
Unlisted is the default posture. A public submission of a link containing a token or an internal address leaks it permanently into a searchable archive.
Rate limits and available visibility levels depend on the plan.
A busy community can exceed a free allowance quickly. Results are cached per URL so a link forwarded fifty times is scanned once.
A scan reports observed behaviour rather than a definitive verdict.
Interpretation is yours. Treating any signal as a binary verdict produces both false positives on legitimate sites and misplaced confidence on novel ones.
How it fails, and what happens when it does
A private URL is submitted publicly.
The worst outcome available here, and permanent. Visibility is set explicitly on every submission rather than inherited from a default nobody checked.
A fresh phishing domain passes screening.
Expected, and why heuristics run alongside — lookalike domains, very recent registration, shortener chains. Neither approach alone is sufficient and the honest answer is "usually, not always".
A legitimate site is flagged because of an unusual redirect.
Suspicious links are warned about rather than removed, so a false positive costs a moment of doubt rather than deleting a member's message.
The API is unavailable during an attack.
Heuristics continue to operate and the community is told screening is degraded. Silently failing open during an active campaign is the worst possible moment for it.
Availability in the UAE and the wider GCC
Global
A public service with no regional restriction. Plan tier governs rate limits and visibility options.
Crypto communities
The intended case here. Phishing volume and the value at stake both justify screening that a general community would find excessive.
Private or internal links
Submitted unlisted or not at all. Public submission archives the URL permanently and searchably.
Free tier
Workable for a small community with result caching. A large one needs a paid plan, and this is a line item rather than an afterthought.
When not to use this integration
- Your community posts links containing tokens or internal addresses. Screening them means submitting them, and that carries its own risk.
- You expect it to catch every phishing link. Fresh domains pass reputation checks by design, and claiming otherwise creates false confidence.
- You want links removed automatically on any suspicion. False positives then delete members' messages, and the community notices.
- Your community is small and slow-moving. Human moderation catches links faster than any screening pipeline at that size.
What it runs on
| Component | Version | Why |
|---|---|---|
| Cloudflare Workers | current | Unfurling, heuristics, submission and result retrieval. |
| Cloudflare D1 | current | Per-URL result cache, verdict history and warning records. |
| Cloudflare KV | current | Short-term cache for repeatedly forwarded links. |
| Zod | 4.4 | Validation of scan results, whose shape varies by scan outcome. |
Questions that come up during scoping
Will this catch a phishing site registered an hour ago?
Reputation feeds will not, because they have not seen it. Behavioural signals from an actual render sometimes will, since the page behaves like the rest of its campaign even on a new domain. The honest answer is usually, not always, which is why heuristics run alongside.
Is it safe to submit any link we see?
Only unlisted. A public submission is archived and permanently searchable, so a link containing a session token or an internal address would be leaked irrecoverably. Visibility is set explicitly on every submission rather than left to a default.
How fast is screening?
Seconds, because the page is actually rendered. Heuristics act immediately on obvious cases so the community is protected while the scan completes, rather than waiting for a verdict on something already recognisable.
Should suspicious links be removed or warned about?
Known-bad links are removed; suspicious ones are warned about. A warning teaches the community what to look for, and a false positive costs a moment of doubt rather than deleting somebody's message.
What happens during a large attack?
Result caching means a link forwarded fifty times is scanned once, which is what keeps volume manageable. If the API becomes unavailable, heuristics continue and the community is told screening is degraded rather than silently failing open.
Is a scan a verdict?
No. It reports observed behaviour and the interpretation is yours. Treating any single signal as binary produces both false positives on legitimate sites and unwarranted confidence about novel ones.
Related reading
The bot this screening sits inside is the anti-scam build.
Spam and raid handling are a separate problem, covered by the moderation build.
Feeding threat intelligence in from elsewhere uses the pattern in the generic webhook integration.
Other services a community bot commonly touches are covered across the full integration list.