// auth and identity
Via APIDescope email verification with pingutil
Descope flows send OTPs and magic links to whatever address a visitor types, and temp-mail inboxes complete them. Add a Generic HTTP connector step before the OTP or magic-link step: it posts the form email to a small endpoint of yours, the endpoint asks pingutil, and a non-200 answer sends the flow down a "use another address" path.
Where it connects: Descope Flows, Generic HTTP connector used as a webhook action in the sign-up flow
What goes wrong without it
- Our Descope sign-up flow is easy to build and just as easy for bots with throwaway inboxes to complete.
- We want the check inside the flow so the block screen matches the rest of our sign-up UI.
- Hard-coding a domain list in a flow condition is impossible to maintain.
What you can do with Descope and pingutil
Block before the OTP is sent
Place the connector action right after the screen that collects form.email. Disposable and randomized addresses get routed to an error screen and no code is sent.
Branch work and personal emails
Return a different status for category free than for company and send personal-email users down a self-serve path while work emails continue to the team setup screen.
Keep the decision logic in code
Thresholds and exceptions live in your endpoint, so changing a rule does not mean editing every flow.
Set it up
- 1
Deploy the endpoint below and set PINGUTIL_KEY and DESCOPE_HOOK_SECRET in its environment.
- 2
In the Descope console, add a Generic HTTP connector with your endpoint as the Base URL and a request header x-hook-secret whose value is a secret holding DESCOPE_HOOK_SECRET.
- 3
In the sign-up flow, add the connector as an action after the email screen, with the JSON body {"email": "{{form.email}}"}.
- 4
Set the action's Generic HTTP Error event to Custom and route it to a screen asking for a different address.
- 5
Use the connector's Test button, then run the flow with a disposable address.
import express from 'express';
const app = express();
app.use(express.json());
// Descope posts {"email": "{{form.email}}"} from the flow.
app.post('/descope/screen-email', async (req, res) => {
if (req.get('x-hook-secret') !== process.env.DESCOPE_HOOK_SECRET) return res.status(401).end();
const email = String(req.body?.email ?? '');
if (!email) return res.status(200).json({ allowed: true });
try {
const r = await fetch('https://pingutil.com/v1/lookup', {
method: 'POST',
headers: {
authorization: 'Bearer ' + process.env.PINGUTIL_KEY,
'content-type': 'application/json',
},
body: JSON.stringify({ input: email, skip_enrichment: true }),
signal: AbortSignal.timeout(2000),
});
if (!r.ok) return res.status(200).json({ allowed: true }); // fail open
const data = await r.json();
// Non-200 triggers the flow's Generic HTTP Error path.
if (data.verdict.is_spam) return res.status(403).json({ allowed: false, reason: data.verdict.reason });
return res.status(200).json({ allowed: true, category: data.category });
} catch {
return res.status(200).json({ allowed: true });
}
});
app.listen(3000);What to do with each result
| pingutil result | Action in Descope |
|---|---|
| verdict.is_spam: true | Endpoint returns 403; the flow takes the custom error path |
| category: "free" | Endpoint returns 200 with category; branch on it if you split personal and work sign-ups |
| category: "company" | Endpoint returns 200; flow continues to OTP or magic link |
| Timeout, 429 or 5xx from pingutil | Endpoint returns 200 (fail open) |
Limits to plan for
- If your own endpoint is down, Descope treats it as a Generic HTTP error and the flow takes the error path. Decide whether that path should block or let the user continue.
- Descope's connector docs describe an optional HMAC signature in the x-descope-webhook-s256 header. The snippet uses a shared-secret header instead; switch to HMAC if you need request signing.
- Fast mode does not test the mailbox. The OTP or magic link itself proves the inbox can receive mail.
Descope documentation
- docs.descope.com/connectors/connector-configuration-guides/network/generic-http
- docs.descope.com/flows/use-cases/backend-webhooks
Descope is a trademark of its owner. This integration uses Descope's documented extension points; it is not an official Descope app.
Common questions
- Can the Descope connector call pingutil directly?
- The Generic HTTP connector supports bearer-token auth, so it can reach the API. A small endpoint of your own is easier to branch on, because the flow only needs a status code and the fail-open logic lives in code.
- Where should the step sit in the flow?
- After the screen that collects the email and before the OTP or magic-link action, so no message is sent to an address you are going to refuse.
Stop bad addresses in Descope today
Sign in with your email, create an API key and paste it into the step above. Test on a few real addresses first: the live demo shows exactly what your Descope setup will receive.