Optitext API Handshake Endpoint

Overview

The handshake endpoint allows external aggregators to complete integration with the Optitext API for sending campaigns. Upon successful completion of the handshake, the external aggregator will be able to send campaigns on behalf of users.

Endpoint Details

• URL: {baseurl}/api/v1.0/aggregator/handshake
• Method: POST
• Content-Type: application/json
• Authentication: Required (see Authentication section)

URL Parameters

• {baseurl} - Provided by the tenant during Optitext API Configuration. Contains the base url plus a Base36-encoded identifier that combines your tenant ID and application ID. This will be provided to the tenant during initial integration setup.

Authentication

The handshake endpoint uses a custom authentication scheme that requires two headers:

Required Headers

1. app-api-key: Your application API key
2. x-hub-signature: HMAC-SHA signature of the request body

How to Generate the Signature

The x-hub-signature header should contain an HMAC signature of the request body using your shared secret key. The signature format follows the GitHub webhook signature format:

x-hub-signature: sha256={signature}

Where {signature} is the hexadecimal HMAC-SHA256 hash of the request body using your shared secret.

Example (Node.js)

const crypto = require("crypto");
const payload = JSON.stringify(requestBody);
const secret = "your-shared-secret";
const signature = crypto
  .createHmac("sha256", secret)
  .update(payload)
  .digest("hex");
const hubSignature = `sha256=${signature}`;

Example (Python)

import hashlib
import hmac
import json
payload = json.dumps(request_body, separators=(',', ':'))
secret = b'your-shared-secret'signature = hmac.new(secret, payload.encode(), hashlib.sha256).hexdigest()
hub_signature = f'sha256={signature}'

Request Format

Request Body

{
  "aggregatorApiKey": "string",
  "campaignSendUrl": "string",
  "senderId": "string"
}

Field Descriptions

• aggregatorApiKey (required): Your aggregator’s API key that will be used for authentication when sending campaigns
• campaignSendUrl (required): The webhook URL where Optitext will send campaign requests to your aggregator
• senderId (required): The sender identifier that will be used for campaigns sent through your aggregator

Response Format

Success Response (200 OK)

{
  "message": "Handshake completed successfully",
  "processedAt": "2024-01-15T10:30:00.000Z"
}

Error Responses

Bad Request (400)

{ "message": "API token, appId, or tenantId is missing." }

Or validation errors:

{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "AggregatorApiKey": ["The AggregatorApiKey field is required."],
    "CampaignSendUrl": ["The CampaignSendUrl field is required."]
  }
}

Conflict (409)

{
    "title": "Duplicate Handshake",
    "message": "Handshake data unchanged for appId: 1, tenantId: 1001. Skipping update.",
    "code": 40901,
    "traceId": "0HNG7S2VFU9UH:00000005"
}

Internal Server Error (500)

{ "message": "Handshake failed." }

Or:

{
  "message": "An error occurred during handshake.",
  "error": "Detailed error message"
}

Complete Example

Request

curl -X POST "https://api.optitext.com/abc123def/api/v1.0/aggregator/handshake" \  -H "Content-Type: application/json" \  -H "app-api-key: your-app-api-key-here" \  -H "x-hub-signature: sha256=calculated-signature-here" \  -d '{    "aggregatorApiKey": "your-aggregator-api-key",    "campaignSendUrl": "https://your-aggregator.com/api/v1/campaigns/send",    "senderId": "YourCompany"  }'

Successful Response

{
  "message": "Handshake completed successfully",
  "processedAt": "2024-01-15T10:30:00.000Z"
}

Integration Flow

1. Pre-requisites:
   • Obtain your baseurl (includes Base36-encoded tenant/app ID)
   • Obtain your app-api-key
   • Obtain your shared secret for signature generation
2. Prepare your endpoint: Set up your campaign send URL that will receive campaign requests from Optitext
3. Generate signature: Create the HMAC-SHA256 signature of your request body
4. Make handshake request: Send the POST request to complete the handshake
5. Handle response: Process the success/error response appropriately

Error Handling

The endpoint returns specific HTTP status codes:

• 200: Handshake completed successfully
• 400: Invalid request (missing required fields, authentication headers, or validation errors)
• 409: Conflict (handshake payload must be unique, duplicate handshake payload was sent)
• 500: Internal server error during handshake processing

Your integration should handle all these scenarios appropriately, with retry logic for 500-level errors if appropriate.

Security Considerations

• Always use HTTPS for requests to protect sensitive data in transit
• Keep your API keys and shared secrets secure and never expose them in client-side code
• Validate the signature on every request to ensure message integrity
• Implement appropriate logging and monitoring for handshake attempts

Rate Limiting

The handshake endpoint is not heavily rate-limited as it’s typically called once per integration. However, implement reasonable retry logic with exponential backoff for failed requests.