# Callbacks & Redirects

Learn how to receive the verification result after a user completes the AgeGO flow.

This guide explains how your site receives the verification result via redirect/callback and grants or denies access accordingly.

AgeGO always follows the same high-level principle:

1. A visitor requests a page on your site.
2. You trigger AgeGO (Overlay or S2S).
3. AgeGO performs the configured Checks (e.g. Selfie, Credit Card, SMS, etc).
4. Your site receives the result and handles access.

## <mark style="color:$primary;">Overview</mark>

Depending on your integration method, the “callback” mechanism is different:

**Modal (Overlay), callback events:** With the Overlay integration, the verification flow runs in-page and your site can react through modal callback events (JavaScript events).

**S2S, redirect back to your site:** With **S2S (server-to-server)**, your server redirects selected users to AgeGO for verification and then receives the result when AgeGO redirects the user back to your site.

## <mark style="color:$primary;">Modal Callback Events</mark>

Use modal events to know what happened in the verification flow (for example, success, failure, underage selection, or returning verified users).

This is the recommended approach for handling “callbacks” in Modal integrations.

Typical uses:

1. Unlock content when verification succeeds.
2. Show an error state when verification fails.
3. Route underage users to an alternative page/experience.
4. Skip unnecessary prompting for returning verified users.

*(Implementation details and the exact event names live in the* [*Modal Integration guide*](/integration/integration/modal-integration-overlay.md#events)*)*

## <mark style="color:$primary;">**S2S Callback via Redirect Back to Your Site**</mark>

### <mark style="color:$info;">**Where the User Returns**</mark>

In S2S, your backend starts verification by redirecting the user to the AgeGO start endpoint.

After verification completes, AgeGO redirects the user back to:

1. The URL in `returnto` (if provided), or
2. The root of your Site’s Website URL (fallback behavior).

### <mark style="color:$info;">**S2S Callback Endpoint**</mark>

Your callback endpoint is simply the page/route on your domain that receives the redirect back from AgeGO (commonly the `returnto` URL).

Your backend should parse the returned parameters, validate them, and decide whether to grant or deny access.

#### <mark style="color:$primary;">Example payloads (what you receive)</mark>

* **S2S return parameters (redirect back to your site)**

After successful or failed verification, the `returnto` URL is modified with GET parameters containing the user status and verification state.

Common fields include:

1. `ag_error`: Error code, if any.
2. `ag_expires`: UNIX timestamp in milliseconds after which the request is expired.
3. `ag_nonce`: The original nonce value (or none).
4. `ag_verified`: yes If successfully verified, otherwise no.
5. `ag_verified_site`: Must match the site used in the initial request (asi).
6. `ag_user_token`: The unique token identifying the verified user.

Integrity fields:

1. `ag_signature`: Checksum of the returned values.
2. `ag_signature_algo`: The algorithm used (e.g. sha256).

*(Full validation logic and code examples live in the S2S guide.)*

## <mark style="color:$primary;">When Callbacks Fire (Success, Cancel, Timeout)</mark>

At a high level, your site should expect a “result” whenever the flow ends in one of these ways:

* Success: the user completes verification successfully.
* Failure / not verified: the user fails verification or does not complete it.
* Underage selection: the user chooses the “I am not 18 years old” CTA (Modal).
* Technical error: network or system error (Modal message / S2S error parameter).
* Timeout / expired: the verification callback expires (S2S uses an expiry timestamp; modal can show an “expired” message).

*(Exact event names and error strings are defined in your Modal “*[*Prompt Messages / Error Messages*](/integration/integration/modal-integration-overlay.md#prompt-messages)*” and S2S “*[*Possible error codes*](/integration/integration/s2s-integration.md#possible-error-codes)*” sections.)*

## <mark style="color:$primary;">**How to Avoid Redirect Loops**</mark>

Redirect loops usually happen when a user is sent to AgeGO again immediately after returning to your site.

Recommended safeguards:

**1) Check verified state before triggering again:** If the user is already verified, do not re-trigger the flow. For S2S, use the returned verification status (`ag_verified`) and your own session state.

**2) Use a `nonce` (recommended):** A `nonce` helps you correlate the return response to a specific session and reduce replay/sharing issues.

**3) Respect expiration:** If the response is expired (`ag_expires`), treat it as invalid and restart the flow only when needed.

**4) Store “verification completed” in your session:** Once a user returns verified, persist that state server-side (S2S) or client-side (Modal) so you don’t trigger again on every page load.

## <mark style="color:$primary;">**Related Guides**</mark>

* [Modal Integration Guide](/integration/integration/modal-integration-overlay.md) → Events, Prompt Messages, Error Messages.
* [S2S Integration Guide](/integration/integration/s2s-integration.md) → Return Parameters, Signature Verification, Error Codes, Code examples.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.agego.com/integration/callbacks-and-redirects.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.