Sending account verification events

Overview

When Castle detects risky or sensitive activity, you can require the user to complete a challenge before continuing. Challenges introduce just enough friction to confirm legitimacy and stop fraud without harming good users.

Castle challenges are flexible. You decide the challenge type that best fits your product. Examples include:

• Email verification: send a one-time link or code to confirm account ownership.
• CAPTCHA: block automated traffic with a bot check.
• Two-Factor Authentication (2FA): prompt for TOTP, SMS, or push verification.
• Custom challenges: integrate with your own flows (e.g., knowledge-based checks, phone call confirmation).

Read more about our recommended ways to challenge users without CAPTCHAs.

Why Challenges Matter for Visibility

Sending challenge events to Castle not only enforces security, but also ensures complete visibility into the user journey:

• Linking signals together: Castle can correlate the original login or action with the issued challenge and its outcome, giving you a single, end-to-end picture of user behavior.
• Understanding user experience: You’ll see how often legitimate users are being challenged, where drop-offs happen, and how challenges affect conversion.
• Measuring effectiveness: By tracking both successful and failed challenges, you can quantify how challenges contribute to stopping fraud (e.g., blocked bots at CAPTCHA, failed OTP attempts).

When to Trigger a Challenge

Typical scenarios where challenges are useful:

• New account signups → confirm ownership of email or phone before account activation.
• Risky login attempts → step-up verification when Castle flags anomalies (new device, location, impossible travel).
• Sensitive account actions → protect password resets, payment method changes, or email updates.
• Suspicious sessions → interrupt high-risk activity (transaction and other in-app actions) flagged by Castle to force re-verification.

How the Challenge Event Works

• Castle returns a challenge verdict in policy.action.
• After you initiate the challenge for the user (e.g., display a CAPTCHA, send an email, prompt for 2FA), send a $challenge $requested event to Castle.
• If the user successfully completes the challenge, send $challenge $succeeded. If the user fails (wrong code, expired link, abandoned CAPTCHA), send $challenge $failed.

📘

Always pass the authentication_method that describes how the challenge was performed.

Always include the challenge object, which ties this challenge to the trigger event that caused it (e.g., $login $attempted).

{
  "type": "$challenge",
	"status": "$requested",

  "authentication_method": {
    "type": "$social",
    "variant": "facebook"
  },

  "challenge": {
    "trigger_event": {
      "type": "$login",
      "status": "$attempted"
    }
  },

  "request_token": "test_lZWva9rsNe3u0_XXXXXXXXXX"
}