Webhooks

Overview

Webhooks allow you to receive real-time notifications when events occur in Antinium. Instead of polling the API, you can set up webhooks to be notified immediately when documents are translated, updated, or shared.

Setting Up Webhooks

1. Go to Settings → Webhooks
2. Click "Create Webhook"
3. Enter your webhook URL (must be HTTPS)
4. Select which events you want to receive
5. Optionally set a secret for verifying webhook signatures
6. Click "Create"

Available Events

Webhook Payload

Webhook payloads are sent as JSON in the request body:

{
  "event": "document.translated",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "document_id": "doc_123",
    "translation_id": "trans_456",
    "target_language": "es",
    "status": "completed"
  }
}

Verifying Webhooks

To verify that webhooks are coming from Antinium, we include a signature in the X-Antinium-Signature header. Verify it using your webhook secret:

// Node.js example
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(payload)).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

// In your webhook handler
const signature = req.headers['x-antinium-signature'];
const isValid = verifyWebhook(req.body, signature, WEBHOOK_SECRET);

if (!isValid) {
  return res.status(401).send('Invalid signature');
}

Webhook Retries

If your webhook endpoint returns an error (4xx or 5xx status code), Antinium will retry the webhook:

• First retry: 1 minute after initial attempt
• Second retry: 5 minutes after first retry
• Third retry: 15 minutes after second retry
• Fourth retry: 1 hour after third retry
• After 4 failed retries, the webhook is marked as failed

Your endpoint should return a 2xx status code within 10 seconds to be considered successful.

Example Webhook Handler

// Express.js example
app.post('/webhooks/antinium', express.json(), (req, res) => {
  // Verify signature
  const signature = req.headers['x-antinium-signature'];
  if (!verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Handle the event
  const { event, data } = req.body;

  switch (event) {
    case 'document.translated':
      console.log('Document translated:', data.document_id);
      // Update your system, send notifications, etc.
      break;
    
    case 'document.updated':
      console.log('Document updated:', data.document_id);
      break;
    
    // Handle other events...
  }

  // Always return 200 to acknowledge receipt
  res.status(200).send('OK');
});

Testing Webhooks

You can test your webhook endpoint:

1. Go to Settings → Webhooks
2. Find your webhook
3. Click "Test"
4. Select an event type to simulate
5. Click "Send test"
6. Check your endpoint to see if it received the webhook

Managing Webhooks

Viewing Webhook Logs

See the delivery status of all webhook events:

1. Go to Settings → Webhooks
2. Click on a webhook
3. View the delivery log
4. See which events were delivered successfully
5. See failed deliveries and retry attempts

Disabling Webhooks

Temporarily disable a webhook without deleting it:

1. Go to Settings → Webhooks
2. Find the webhook
3. Toggle it to "Disabled"
4. No events will be sent while disabled
5. Re-enable it anytime

Best Practices

• Verify signatures: Always verify webhook signatures to ensure they're from Antinium
• Respond quickly: Return a 200 status code within 10 seconds
• Handle idempotency: Events may be delivered multiple times - make your handler idempotent
• Log everything: Log all webhook events for debugging
• Use HTTPS: Webhook endpoints must use HTTPS
• Test thoroughly: Use the test feature to verify your endpoint works

Related Topics

• API Overview - General API information
• Translation Endpoints - Translation API