User-X Platform Integration Guide

This comprehensive guide covers API integration, webhook implementation, and international deployment for the User-X platform.

Table of Contents

1. API Overview
2. Authentication
3. Webhook System
4. International Deployment
5. GDPR Compliance

API Overview

The User-X platform provides a comprehensive REST API for managing users, opportunities, tasks, verifications, and rewards. The API is built on Next.js with TypeScript and uses MongoDB for data persistence.

Base URLs

• Development: http://userdev.lmatrixapp.com/api
• Production: https://api.user-x.com

Core Entities

• Users: Platform participants who complete tasks
• Opportunities: Campaigns or challenges available to users
• Tasks: Individual actions within opportunities
• Verifications: Proof submissions for task completion
• Claims: User participation in opportunities
• Rewards: Benefits earned upon successful completion

Authentication

The platform supports multiple authentication methods:

JWT Token Authentication

Authorization: Bearer <jwt_token>

API Token Authentication

For server-to-server communication:

Authorization: Bearer <api_token>

Auth0 Integration

For business users and dashboard access:

• OAuth 2.0 / OpenID Connect
• Social login support
• Multi-factor authentication

Webhook System

The platform implements a comprehensive webhook system to notify external systems of important events.

Verification Webhook

When a task verification is submitted, a webhook is sent to notify external systems about the verification details and status.

Endpoint Configuration

The verification webhook is configured using the following environment variables:

VERIFICATION_WEBHOOK_URL=https://your-domain.com/webhooks/verification
VERIFICATION_WEBHOOK_SECRET=your-secure-secret

Request Details

• Method: POST
• Content-Type: application/json
• Authentication: Bearer token (using VERIFICATION_WEBHOOK_SECRET)

Payload Structure

{
  "verification": {
    "id": "verification_id",
    "taskId": "task_id",
    "claimId": "claim_id",
    "text": "User verification text",
    "assets": [
      {
        "uri": "https://cloudinary.com/image.jpg",
        "mediaType": "image",
        "caption": "Task completion proof"
      }
    ],
    "surveyResponses": [
      {
        "questionId": "question_1",
        "answer": "User's answer"
      }
    ],
    "status": "pending",
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "user": {
    "id": "user_id",
    "email": "[email protected]",
    "name": "John Doe"
  },
  "task": {
    "id": "task_id",
    "title": "Complete Survey",
    "description": "Fill out the feedback survey"
  },
  "opportunity": {
    "id": "opportunity_id",
    "title": "Customer Feedback Campaign",
    "description": "Help us improve our services"
  }
}

Success Response

Your webhook endpoint should return a 200 status code to acknowledge receipt:

{
  "received": true,
  "timestamp": "2024-01-15T10:30:00Z"
}

Error Handling

If your webhook endpoint returns a non-200 status code, the system will retry the webhook delivery up to 3 times with exponential backoff.

Example Usage

// Express.js webhook handler
app.post('/webhooks/verification', (req, res) => {
  const { verification, user, task, opportunity } = req.body;

  // Verify the webhook secret
  const receivedSecret = req.headers.authorization?.replace('Bearer ', '');
  if (receivedSecret !== process.env.VERIFICATION_WEBHOOK_SECRET) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  // Process the verification
  console.log(`New verification from ${user.name} for task: ${task.title}`);

  // Your business logic here
  processVerification(verification);

  res.status(200).json({ received: true });
});

Claim Completion Webhook

Triggered when all tasks in a claim are completed and approved.

Endpoint Configuration

WEBHOOK_URL=https://your-domain.com/webhooks/claim
WEBHOOK_SECRET=your-secure-secret

Payload Structure

{
  "claim": {
    "id": "claim_id",
    "opportunityId": "opportunity_id",
    "userId": "user_id",
    "status": "completed",
    "completedAt": "2024-01-15T10:30:00Z",
    "verifications": [
      {
        "id": "verification_1",
        "taskId": "task_1",
        "status": "approved"
      }
    ]
  },
  "user": {
    "id": "user_id",
    "email": "[email protected]",
    "name": "John Doe"
  },
  "opportunity": {
    "id": "opportunity_id",
    "title": "Customer Feedback Campaign",
    "totalTasks": 3,
    "completedTasks": 3
  }
}

Reward Webhook

Triggered when rewards are generated after successful claim completion.

Endpoint Configuration

REWARD_WEBHOOK_URL=https://your-domain.com/webhooks/reward
REWARD_WEBHOOK_SECRET=your-secure-secret

Payload Structure

{
  "reward": {
    "id": "reward_id",
    "claimId": "claim_id",
    "userId": "user_id",
    "type": "voucher",
    "value": 25.00,
    "currency": "USD",
    "voucherCode": "REWARD123",
    "expiresAt": "2024-12-31T23:59:59Z",
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "user": {
    "id": "user_id",
    "email": "[email protected]",
    "name": "John Doe"
  },
  "claim": {
    "id": "claim_id",
    "opportunityId": "opportunity_id",
    "completedAt": "2024-01-15T10:30:00Z"
  }
}

Security

1. The webhook uses Bearer token authentication
2. All communication should be over HTTPS
3. The webhook secret should be kept secure and rotated periodically
4. The webhook endpoint should validate the Bearer token
5. Consider implementing webhook signature validation for additional security

API Usage Examples

Get Active Opportunities

GET /api/opportunities
Authorization: Bearer <jwt_token>

Submit Task Verification

POST /api/verifications
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "taskId": "task_id",
  "claimId": "claim_id",
  "text": "Verification text",
  "assets": [
    {
      "uri": "https://example.com/image.jpg",
      "mediaType": "image",
      "caption": "Task completion proof"
    }
  ]
}

Generate API Token

POST /api/generate-token
Authorization: Bearer <auth0_token>

International Deployment

The User-X platform is designed for global deployment with built-in support for multiple regions and GDPR compliance.

Multi-Region Architecture

Our deployment methodology ensures data sovereignty and optimal performance across international markets:

Regional Deployment Strategy

1. Primary Regions

   • North America: us-west1 (Primary), us-east1 (Secondary)
   • Europe: europe-west1 (Primary), europe-west3 (Secondary)
   • Asia Pacific: asia-southeast1 (Primary), asia-northeast1 (Secondary)

2. Data Residency Compliance

   • EU data remains within EU boundaries (GDPR Article 44-49)
   • US data processed within US jurisdiction
   • Asia-Pacific data localized to respective regions

3. Infrastructure Components

   • Application Layer: Firebase Hosting with regional CDN
   • Database: MongoDB Atlas with regional clusters
   • File Storage: Cloudinary with regional optimization
   • Real-time Services: Firebase Realtime Database per region

GDPR Compliance Framework

Data Protection Measures

1. Data Minimization (Article 5)

   • Only collect necessary user data
   • Automatic data retention policies
   • Regular data audits and cleanup

2. Consent Management (Article 7)

   • Explicit consent for data processing
   • Granular privacy controls
   • Easy consent withdrawal mechanisms

3. Right to be Forgotten (Article 17)

   • Complete user data deletion APIs
   • Cascading deletion across all services
   • Verification of data removal

4. Data Portability (Article 20)

   • User data export functionality
   • Standardized data formats
   • Secure transfer mechanisms

This deployment methodology ensures full compliance with international data protection regulations while maintaining optimal performance and user experience across all regions.