> For the complete documentation index, see [llms.txt](https://docs.stopbot.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stopbot.net/main/workflow-overview.md).

# Workflow Overview

The workflow is designed to help your website make fast security decisions while keeping the result easy to review from the STOPBOT panel.

### Workflow Diagram

```mermaid
flowchart TD
    A[Visitor, Bot, or Crawler] --> B[Your Website, App, or SmartURLs]
    B --> C[Send Visitor Context]
    C --> D[STOPBOT]
    D --> E[Validate Account and Request]
    E --> F[Analyze Visitor Risk]
    F --> G{Decision}

    G -- Safe --> H[Allow Visitor]
    G -- Suspicious --> I[Block Visitor]
    G -- Custom Rule --> J[Redirect Visitor]
    G -- Page Rule --> K[Return Page Response]
    G -- Browser Check --> L[Run JavaScript Verification]

    H --> M[Activity Appears in STOPBOT Panel]
    I --> M
    J --> M
    K --> M
    L --> M
```

### Traffic Decision Diagram

```mermaid
flowchart TD
    A[Visitor Request] --> B[Validate Integration]
    B --> C[Load Your Protection Rules]
    C --> D[Check Visitor Identity]
    D --> E[Review IP, Location, Device, Browser, and URL]
    E --> F[Compare With Allowlist and Block Rules]
    F --> G[Evaluate Threat Signals]
    G --> H{Final Result}

    H -- Trusted --> I[Allow Access]
    H -- Blocked --> J[Block Access]
    H -- Needs Action --> K[Redirect or Show Custom Response]

    I --> L[Return Result to Your Website]
    J --> L
    K --> L
    L --> M[Update Panel Insights]
```

### SmartURLs Verification Diagram

```mermaid
sequenceDiagram
    participant V as Visitor Browser
    participant S as SmartURLs Website
    participant A as STOPBOT
    participant P as STOPBOT Panel

    V->>S: Open /{keyname}
    S->>A: Request SmartURLs decision
    A->>S: Return allow, block, redirect, or verification required

    alt JavaScript verification required
        S->>V: Render verification page
        V->>S: Browser completes verification
        S->>A: Confirm verification result
        A->>S: Verification accepted
    else No JavaScript verification
        A->>S: Continue without extra browser check
    end

    S->>V: Redirect or show the configured response
    A-->>P: Visitor activity appears in reports
```

### Blocker V2 Page Response Diagram

```mermaid
flowchart TD
    A[Visitor Opens Protected Page] --> B[Your Website Sends Visitor Context]
    B --> C[STOPBOT Reviews Configuration]
    C --> D[STOPBOT Analyzes Risk Signals]
    D --> E[STOPBOT Returns Decision and Page Response]

    E --> F{Should Access Be Blocked?}
    F -- No --> G[Show Normal Page]
    F -- Yes --> H{Configured Response}

    H -- Redirect --> I[Send Visitor to Another URL]
    H -- HTTP Status --> J[Return Custom HTTP Status]
    H -- Default Block --> K[Show Block Response]
```

### Panel Insights Diagram

```mermaid
flowchart LR
    A[Protected Traffic] --> B[STOPBOT Decision]
    B --> C[Activity Processing]
    C --> D[STOPBOT Panel]
    D --> E[Dashboard]
    D --> F[Recent Logs]
    D --> G[Blocker Reports]
    D --> H[SmartURLs Reports]
    D --> I[Blocker V2 Reports]
```

### Complete System Flow

```
Visitor
  ->
Your website, app, or SmartURLs
  ->
Visitor context is sent to STOPBOT
  ->
STOPBOT validates the request
  ->
STOPBOT analyzes visitor risk
  ->
STOPBOT returns a decision
  ->
Your website applies the decision
  ->
Activity can be reviewed in the STOPBOT panel
```

### Main Components

| Component           | Purpose                                                                        |
| ------------------- | ------------------------------------------------------------------------------ |
| Visitor             | The person, bot, crawler, or automated request visiting your website           |
| Your website or app | Sends visitor context to STOPBOT before deciding what to do                    |
| SmartURLs           | Handles shortlink traffic and redirect decisions                               |
| STOPBOT             | Validates the request, analyzes visitor risk, and returns a decision           |
| Protection rules    | Your allowlist, block rules, country rules, device rules, and service settings |
| STOPBOT panel       | Shows traffic activity, protection results, and service reports                |

### 1. Visitor Reaches Your Website

A visitor opens a protected page, shortlink, landing page, checkout page, login page, or any other page where STOPBOT protection is enabled.

At this point, your website can collect the visitor context needed for analysis:

* IP address
* user agent
* requested URL
* optional request parameters
* optional request headers

The API key should stay on your server. Do not expose it in public frontend JavaScript.

### 2. Your Website Sends A Request To STOPBOT

Your server sends the visitor context to the correct STOPBOT service.

| Service               | Main Purpose                                                      |
| --------------------- | ----------------------------------------------------------------- |
| Account               | Check account status, usage, quota, and expiration                |
| Blocker               | Detect and block suspicious traffic before it reaches your page   |
| SmartURLs             | Analyze shortlink visitors and return the correct redirect action |
| Blocker V2            | Apply advanced protection rules and custom page responses         |
| IP Lookup             | Return IP, location, ISP, ASN, and network information            |
| Email Validation      | Check email format, domain, MX, SPF, DMARC, and disposable status |
| Phone Number Identify | Validate and identify phone number information                    |

### 3. STOPBOT Validates The Request

Before analyzing traffic, STOPBOT checks that the request is allowed to continue.

Validation includes:

* API key is valid
* account is active
* quota is available
* required parameters are present
* service configuration exists
* SmartURLs keyname or Blocker V2 configuration belongs to the account

If validation fails, STOPBOT returns an error response so your integration can handle it clearly.

### 4. STOPBOT Analyzes Visitor Risk

After validation, STOPBOT reviews the visitor using several security signals.

Common checks include:

* IP reputation
* location and country rules
* device and browser information
* user agent behavior
* hostname and network information
* URL threat signals
* allowlist and blocklist rules
* SmartURLs or Blocker V2 configuration

The goal is to decide whether the visitor looks safe, suspicious, blocked, or requires an additional browser check.

### 5. STOPBOT Returns A Decision

STOPBOT returns a decision that your website can apply immediately.

Possible results include:

| Result                  | What Your Website Should Do                                         |
| ----------------------- | ------------------------------------------------------------------- |
| Allow                   | Continue loading the normal page                                    |
| Block                   | Stop the visitor from accessing the protected content               |
| Redirect                | Send the visitor to the configured destination                      |
| HTTP status             | Return the configured HTTP response code                            |
| JavaScript verification | Ask the visitor browser to complete an additional verification step |
| Lookup result           | Display or process the returned lookup or validation data           |

### 6. Blocker Workflow

The Blocker service is used when your website wants a simple allow-or-block decision.

```
Visitor opens page
  ->
Your server sends IP, user agent, and URL
  ->
STOPBOT checks visitor risk and your rules
  ->
STOPBOT returns allow or block result
  ->
Your website continues or blocks the request
```

Use this workflow for pages where suspicious traffic should be stopped before the page is served.

### 7. SmartURLs Workflow

SmartURLs is used when a shortlink needs to decide whether a visitor should be redirected, blocked, or verified first.

```
Visitor opens shortlink
  ->
SmartURLs sends visitor context and keyname to STOPBOT
  ->
STOPBOT checks the keyname and visitor risk
  ->
STOPBOT returns redirect, block, or verification result
  ->
SmartURLs applies the result
```

If JavaScript verification is required, the visitor browser completes the verification step before the final redirect.

### 8. Blocker V2 Workflow

Blocker V2 is used when your website needs more advanced traffic control and custom page behavior.

```
Visitor opens protected page
  ->
Your server sends visitor context and configuration name
  ->
STOPBOT analyzes IP, browser, URL, parameters, headers, and rules
  ->
STOPBOT returns block status and page response
  ->
Your website shows the normal page, redirects, or returns a custom response
```

Use this workflow when you need more detailed protection logic for important pages.

### 9. Lookup And Validation Workflows

Some services return information instead of a traffic decision.

| Service               | Returned Result                                                   |
| --------------------- | ----------------------------------------------------------------- |
| Account               | Account package, quota, usage, and expiration status              |
| IP Lookup             | IP location, network, ISP, ASN, and hostname information          |
| Email Validation      | Email syntax, domain, MX, SPF, DMARC, and disposable email status |
| Phone Number Identify | Phone validity, type, carrier, country, and location information  |

These services are useful for enrichment, verification, and application-side decision-making.

### 10. Panel Insights

After protected traffic is processed, results can be reviewed in the STOPBOT panel.

Panel insights may include:

* total traffic
* allowed visitors
* blocked visitors
* detected bots
* countries and devices
* SmartURLs activity
* Blocker and Blocker V2 reports
* API usage

This helps you monitor protection performance and understand how visitors are being handled.

### 11. Error Workflow

If a request cannot be processed, STOPBOT returns a clear error response.

| Situation                          | Meaning                                                                 |
| ---------------------------------- | ----------------------------------------------------------------------- |
| Bad request                        | Required parameters are missing or invalid                              |
| Unauthorized                       | API key is invalid or not recognized                                    |
| Payment required                   | Quota is exhausted or the account is expired                            |
| Not found or invalid configuration | The requested keyname or configuration is not available for the account |
| Service unavailable                | STOPBOT cannot process the request at that moment                       |

Your integration should handle these responses gracefully, especially on production pages.

### 12. Production Checklist

Before enabling STOPBOT on a live website, confirm that:

* the API key is active
* the API key is only used server-side
* quota is available
* visitor IP forwarding is correct behind Cloudflare or a reverse proxy
* SmartURLs keynames are registered
* Blocker V2 configuration names are registered
* allow, block, redirect, and HTTP status behavior has been tested
* logs and reports appear in the STOPBOT panel

### Final Workflow Summary

```
Visitor reaches your website
  ->
Your website sends visitor context to STOPBOT
  ->
STOPBOT validates the request
  ->
STOPBOT analyzes visitor risk
  ->
STOPBOT returns a decision
  ->
Your website applies the result
  ->
STOPBOT panel shows activity and reports
```

This workflow gives your website real-time protection while keeping the result easy to understand, monitor, and improve from the STOPBOT panel.