Custom Integration

Building a custom Treblle Integration allows you to integrate Treblle with frameworks or languages we don’t officially support yet.

This guide walks you through creating a production-ready Integration that captures API data and sends it to Treblle.

When to Build a Custom Integration

Consider building a custom Integration when:

• Your framework/language isn’t in our official Integrations
• You need specialized functionality for your infrastructure
• You’re building a proprietary framework that needs Treblle Integration
• You want to contribute back to the Treblle ecosystem

How Treblle Integrations Work

Treblle Integrations act as middleware that:

1. Intercept requests before they reach your application
2. Capture request/response data without modifying the API behavior
3. Mask sensitive information before it leaves your server
4. Send data asynchronously to Treblle’s servers for analysis

Core Requirements

Every Treblle Integration must implement these essential components:

1. Request/Response Capture

Your Integration needs access to:

• Request method, URL, headers, and body
• Response status code, headers, body, and timing
• Server information (IP, timezone, OS details)

Most frameworks provide this through middleware hooks or request interceptors.

2. Data Masking

Implement masking for:

Default masked fields:

password, pwd, secret, password_confirmation, 
cc, card_number, ccv, ssn, credit_score, api_key

Masking strategy:

• Replace field values with asterisks (*) matching the original length
• Apply to request/response bodies, headers, and nested objects
• Allow custom field configuration

3. Treblle Payload Format

Your Integration must format data according to Treblle’s JSON schema and send it to one of these endpoints:

https://rocknrolla.treblle.com
https://punisher.treblle.com  
https://sicario.treblle.com

Implementation Steps

Step 1: Framework Integration

Identify how to hook into your framework’s request lifecycle:

// Example: Express.js middleware pattern
function treblleMiddleware(req, res, next) {
  // Capture request data
  const startTime = Date.now();
  
  // Continue to application
  next();
  
  // Capture response data after completion
  res.on('finish', () => {
    const endTime = Date.now();
    // Send to Treblle
  });
}

Step 2: Data Collection

Gather the required information:

const treblleData = {
  api_key: "YOUR_API_KEY",
  SDK_TOKEN: "YOUR_SDK_TOKEN", 
  version: 1.0,
  sdk: "your-framework-name",
  data: {
    server: { /* server info */ },
    language: { /* runtime info */ },
    request: { /* request details */ },
    response: { /* response details */ },
    errors: [] /* any captured errors */
  }
};

Step 3: Implement Masking

Create a masking function that processes nested objects:

function maskSensitiveData(data, maskingKeywords) {
  // Recursively traverse objects/arrays
  // Replace values for keys matching maskingKeywords
  // Return masked copy of data
}

Step 4: Send to Treblle

Make an asynchronous POST request:

function sendToTreblle(data) {
  const endpoints = [
    'https://rocknrolla.treblle.com',
    'https://punisher.treblle.com', 
    'https://sicario.treblle.com'
  ];
  
  const endpoint = endpoints[Math.floor(Math.random() * endpoints.length)];
  
  // Send POST request with data
  // Handle errors gracefully - don't break user's API
}

JSON Schema Reference

Your payload must match this structure:

{
  "api_key": "string",
  "SDK_TOKEN": "string", 
  "version": "number|string",
  "sdk": "string",
  "data": {
    "server": {
      "ip": "string",
      "timezone": "string", 
      "os": {
        "name": "string",
        "release": "string",
        "architecture": "string"
      },
      "software": "string|null",
      "signature": "string|null", 
      "protocol": "string",
      "encoding": "string"
    },
    "language": {
      "name": "string",
      "version": "string"
    },
    "request": {
      "timestamp": "string",
      "ip": "string",
      "url": "string", 
      "user_agent": "string",
      "method": "string",
      "headers": "object",
      "body": "object"
    },
    "response": {
      "headers": "object",
      "code": "integer", 
      "size": "integer|string",
      "load_time": "number",
      "body": "string|object|null"
    },
    "errors": "array"
  }
}

Configuration

Provide these configuration options:

const treblle = new TreblleSDK({
  apiKey: "required",
  sdkToken: "required", 
  additionalFieldsToMask: ["custom_field"], // optional
  enabledEnvironments: ["production"], // optional
  debug: false // optional
});

Testing Your Integration

Examples and Reference

Study existing Integrations for implementation patterns:

• PHP Integration  - Framework-agnostic approach
• Express.js Integration  - Middleware pattern
• Laravel Integration  - Framework-specific Integration

Frequently Asked Questions

Getting Support

• Integration submission: Email hello@treblle.com
• Documentation: This guide and JSON schema reference

Contributing Back

Once your Integration is working:

1. Open source it on GitHub
2. Submit it to our community Integrations list
3. Consider making it an official Treblle Integration

Building a custom Integration helps expand Treblle’s ecosystem and enables more developers to benefit from API Intelligence.