Webhooks

Receive real-time notifications when events occur in Cultural Translate.

Setting Up Webhooks

Via Web Interface

1. Go to Project Settings → Webhooks
2. Click "Add Webhook"
3. Enter endpoint URL
4. Select events to subscribe to
5. Save

Via API

POST /api/v1/webhooks
{
  "url": "https://yourapp.com/webhooks/gotranslate",
  "events": [
    "translation.completed",
    "translation.failed",
    "project.updated"
  ],
  "secret": "your_webhook_secret",
  "active": true
}

Available Events

Translation Events

• translation.created - New translation requested
• translation.completed - Translation finished
• translation.failed - Translation failed
• translation.updated - Translation edited
• translation.approved - Translation approved

Project Events

• project.created - New project created
• project.updated - Project settings changed
• project.deleted - Project removed

File Events

• file.uploaded - File uploaded for translation
• file.completed - File translation finished
• file.exported - Translated file exported

Webhook Payload

All webhooks include:

{
  "event": "translation.completed",
  "timestamp": "2025-12-04T21:30:00Z",
  "data": {
    "id": "trans_123",
    "project_id": "proj_456",
    "source_text": "Hello",
    "translated_text": "مرحباً",
    "source_language": "en",
    "target_language": "ar",
    "status": "completed",
    "engine": "ai",
    "created_at": "2025-12-04T21:29:45Z",
    "completed_at": "2025-12-04T21:30:00Z"
  }
}

Security

Signature Verification

Verify webhook authenticity using HMAC signatures:

// PHP Example
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_GOTRANSLATE_SIGNATURE'];
$secret = 'your_webhook_secret';

$computed = hash_hmac('sha256', $payload, $secret);

if (!hash_equals($signature, $computed)) {
    http_response_code(401);
    die('Invalid signature');
}

IP Whitelist

Cultural Translate webhooks come from these IPs:

145.14.158.101
185.199.108.0/22
192.30.252.0/22

Retry Logic

Failed webhooks are retried with exponential backoff:

• 1st retry: after 1 minute
• 2nd retry: after 5 minutes
• 3rd retry: after 15 minutes
• 4th retry: after 1 hour
• 5th retry: after 6 hours

Response Requirements

Your endpoint must:

• Return HTTP 2xx status code within 10 seconds
• Accept JSON content type
• Handle duplicate deliveries (idempotent)

Testing Webhooks

Send test webhook from the dashboard:

POST /api/v1/webhooks/{webhook_id}/test

Response:
{
  "success": true,
  "status_code": 200,
  "response_time_ms": 145
}

Webhook Logs

View delivery history and debug failed webhooks:

• Last 30 days of webhook deliveries
• Request/response details
• Retry attempts
• Error messages