Integration

Integration Guide

Examples for integrating ECURTIY with popular frameworks and platforms.

Integration Overview

ECURTIY integration consists of two parts:

Client-Side

Add the widget script to your HTML. The widget handles the verification UI and generates a token on success.

Server-Side

Validate the token on your server using the /api/validate endpoint with your secret key.

Supported Frameworks

🟢Node.js

🐍Python

🐘PHP

💎Ruby

🔵Go

☕Java

🟢Node.js / Express

Server-side validation with Express.js

const express = require('express');
const app = express();

app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// Validation helper
async function validateEcurtiy(token) {
  const response = await fetch('https://your-domain.com/api/validate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      token,
      secretKey: process.env.ECURTIY_SECRET_KEY
    })
  });
  return response.json();
}

// Protected form endpoint
app.post('/contact', async (req, res) => {
  const { 'ecurtiy-token': token, name, email, message } = req.body;

  // Validate ECURTIY token
  const validation = await validateEcurtiy(token);

  if (!validation.success || !validation.data.passed) {
    return res.status(400).json({ error: 'Verification failed' });
  }

  // Optional: Check risk score
  if (validation.data.riskScore > 0.5) {
    console.log('High risk submission, flagging for review');
  }

  // Process the form...
  res.json({ success: true });
});

🐍Python / Flask

Server-side validation with Flask

from flask import Flask, request, jsonify
import requests
import os

app = Flask(__name__)

def validate_ecurtiy(token):
    response = requests.post(
        'https://your-domain.com/api/validate',
        json={
            'token': token,
            'secretKey': os.environ.get('ECURTIY_SECRET_KEY')
        }
    )
    return response.json()

@app.route('/contact', methods=['POST'])
def contact():
    token = request.form.get('ecurtiy-token')

    # Validate ECURTIY token
    validation = validate_ecurtiy(token)

    if not validation.get('success') or not validation.get('data', {}).get('passed'):
        return jsonify({'error': 'Verification failed'}), 400

    # Check risk score
    risk_score = validation.get('data', {}).get('riskScore', 0)
    if risk_score > 0.5:
        app.logger.warning(f'High risk submission: {risk_score}')

    # Process the form...
    return jsonify({'success': True})

🐘PHP

Server-side validation with PHP

<?php

function validateEcurtiy($token) {
    $ch = curl_init('https://your-domain.com/api/validate');

    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode([
            'token' => $token,
            'secretKey' => getenv('ECURTIY_SECRET_KEY')
        ])
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $token = $_POST['ecurtiy-token'] ?? '';

    // Validate ECURTIY token
    $validation = validateEcurtiy($token);

    if (!$validation['success'] || !$validation['data']['passed']) {
        http_response_code(400);
        echo json_encode(['error' => 'Verification failed']);
        exit;
    }

    // Check risk score
    if ($validation['data']['riskScore'] > 0.5) {
        error_log('High risk submission: ' . $validation['data']['riskScore']);
    }

    // Process the form...
    echo json_encode(['success' => true]);
}

▲Next.js (App Router)

API route handler for Next.js 14+

// app/api/contact/route.ts
import { NextRequest, NextResponse } from 'next/server'

async function validateEcurtiy(token: string) {
  const response = await fetch('https://your-domain.com/api/validate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      token,
      secretKey: process.env.ECURTIY_SECRET_KEY
    })
  })
  return response.json()
}

export async function POST(request: NextRequest) {
  const formData = await request.formData()
  const token = formData.get('ecurtiy-token') as string

  // Validate ECURTIY token
  const validation = await validateEcurtiy(token)

  if (!validation.success || !validation.data.passed) {
    return NextResponse.json(
      { error: 'Verification failed' },
      { status: 400 }
    )
  }

  // Process the form...
  return NextResponse.json({ success: true })
}

Webhook Integration

Configure webhooks in your site settings to receive real-time verification events:

// Webhook payload example
{
  "event": "verification.complete",
  "siteId": "site_abc123",
  "timestamp": "2024-12-08T12:00:00Z",
  "data": {
    "verificationId": "ver_xyz789",
    "passed": true,
    "riskScore": 0.15,
    "solveTimeMs": 1850,
    "mode": "checkbox",
    "ipAddress": "203.0.113.1",
    "userAgent": "Mozilla/5.0..."
  }
}

// Your webhook endpoint
app.post('/webhooks/ecurtiy', (req, res) => {
  const { event, data } = req.body;

  if (event === 'verification.complete') {
    if (!data.passed || data.riskScore > 0.6) {
      // Flag for review
      flagSuspiciousActivity(data);
    }
  }

  res.status(200).send('OK');
});

Pro Tip:

Use webhooks for real-time monitoring and fraud detection. Available on Pro plans and above.

Best Practices

Always validate server-side
Never trust client-side verification alone. Always call /api/validate from your server.
Store secret key securely
Use environment variables for your secret key. Never expose it in client-side code.
Handle errors gracefully
Provide clear feedback when verification fails. Don't expose internal error details.
Use risk scores
Implement additional verification for high-risk scores instead of blocking outright.
Monitor analytics
Regularly check your dashboard for unusual patterns or high failure rates.
Set up webhooks
Use webhooks for real-time monitoring and to trigger alerts on suspicious activity.

Getting Started Security