Tengine.AI
← Back to Dashboard

Webhooks Guide

Set up webhooks to receive real-time notifications from TengineAI.

Overview

Webhooks allow your application to receive notifications when events occur in your TengineAI projects. This enables real-time integration and automated workflows.

Supported Events

Project Events

  • project.created: New project created
  • project.updated: Project settings updated
  • project.deleted: Project deleted

API Key Events

  • api_key.created: New API key generated
  • api_key.revoked: API key revoked
  • api_key.updated: API key permissions updated

Integration Events

  • integration.connected: OAuth integration connected
  • integration.disconnected: OAuth integration disconnected
  • integration.updated: Integration settings updated

Usage Events

  • usage.threshold_reached: Usage threshold exceeded
  • usage.limit_exceeded: Usage limit exceeded

Setting Up Webhooks

Via Dashboard

  1. Navigate to Webhooks

    • Go to your project settings
    • Click "Webhooks" in the sidebar
    • Click "Add Webhook"

  2. Configure Webhook

    • Enter your webhook URL
    • Select events to subscribe to
    • Set up authentication (optional)

  3. Test Webhook

    • Send a test event
    • Verify your endpoint receives it
    • Check the response format

Via API

curl -X POST https://app.tengine.ai/api/v1/projects/{project_id}/webhooks \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://your-app.com/webhook",
       "events": ["project.created", "api_key.created"],
       "secret": "your-webhook-secret"
     }'

Webhook Payload

Event Structure

{
  "id": "evt_1234567890",
  "type": "project.created",
  "data": {
    "id": "proj_123",
    "name": "My Project",
    "description": "A sample project",
    "created_at": "2024-01-01T00:00:00Z"
  },
  "created_at": "2024-01-01T00:00:00Z",
  "api_version": "2021-09-01"
}

Event Types

Project Created

{
  "type": "project.created",
  "data": {
    "id": "proj_123",
    "name": "My Project",
    "description": "Project description",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

API Key Created

{
  "type": "api_key.created",
  "data": {
    "id": "key_123",
    "name": "My API Key",
    "permissions": ["read", "write"],
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Webhook Security

Signature Verification

TengineAI signs all webhook payloads using HMAC-SHA256:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  return signature === `sha256=${expectedSignature}`;
}

// Usage
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-tengine-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(400).send('Invalid signature');
  }
  
  // Process webhook
  res.status(200).send('OK');
});

IP Whitelisting

For additional security, whitelist TengineAI IP addresses:

# TengineAI Webhook IPs
54.123.45.67
54.123.45.68

Handling Webhooks

Basic Handler

app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-tengine-signature'];
  
  // Verify signature
  if (!verifyWebhookSignature(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(400).send('Invalid signature');
  }
  
  const event = JSON.parse(req.body);
  
  // Handle different event types
  switch (event.type) {
    case 'project.created':
      handleProjectCreated(event.data);
      break;
    case 'api_key.created':
      handleApiKeyCreated(event.data);
      break;
    default:
      console.log(`Unhandled event type: ${event.type}`);
  }
  
  res.status(200).send('OK');
});

Retry Logic

TengineAI will retry failed webhook deliveries:

  • Initial attempt: Immediate
  • Retry 1: After 1 minute
  • Retry 2: After 5 minutes
  • Retry 3: After 15 minutes
  • Retry 4: After 1 hour
  • Retry 5: After 4 hours

Idempotency

Handle duplicate events using the event ID:

const processedEvents = new Set();

app.post('/webhook', (req, res) => {
  const event = JSON.parse(req.body);
  
  // Check if already processed
  if (processedEvents.has(event.id)) {
    return res.status(200).send('Already processed');
  }
  
  // Process event
  processEvent(event);
  
  // Mark as processed
  processedEvents.add(event.id);
  
  res.status(200).send('OK');
});

Testing Webhooks

Local Development

Use ngrok to expose your local server:

# Install ngrok
npm install -g ngrok

# Expose local server
ngrok http 3000

# Use the HTTPS URL for webhook endpoint
# https://abc123.ngrok.io/webhook

Webhook Testing Tools

# Send test webhook
curl -X POST https://app.tengine.ai/api/v1/webhooks/{webhook_id}/test \
     -H "Authorization: Bearer YOUR_API_KEY"

Monitoring and Debugging

Webhook Logs

View webhook delivery logs in your dashboard:

  1. Go to project settings
  2. Click "Webhooks"
  3. Click on a webhook to view logs
  4. Check delivery status and responses

Common Issues

"Invalid Signature"

  • Verify webhook secret is correct
  • Check signature calculation
  • Ensure payload is raw JSON

"Timeout"

  • Implement quick response (under 5 seconds)
  • Use async processing for heavy operations
  • Return 200 status immediately

"Duplicate Events"

  • Implement idempotency checking
  • Use event IDs to track processed events
  • Handle retry scenarios gracefully

Best Practices

Response Handling

app.post('/webhook', (req, res) => {
  try {
    // Quick validation
    const event = JSON.parse(req.body);
    
    // Return 200 immediately
    res.status(200).send('OK');
    
    // Process asynchronously
    setImmediate(() => {
      processWebhookEvent(event);
    });
    
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(400).send('Bad Request');
  }
});

Error Handling

async function processWebhookEvent(event) {
  try {
    // Process event
    await handleEvent(event);
  } catch (error) {
    console.error('Failed to process webhook:', error);
    // Log to monitoring service
    // Send alert to team
  }
}

Advanced Configuration

Custom Headers

curl -X POST https://app.tengine.ai/api/v1/projects/{project_id}/webhooks \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://your-app.com/webhook",
       "events": ["project.created"],
       "headers": {
         "X-Custom-Header": "custom-value"
       }
     }'

Event Filtering

{
  "url": "https://your-app.com/webhook",
  "events": ["project.created", "api_key.created"],
  "filters": {
    "project.name": "My Project"
  }
}

Next Steps

Need help with webhooks? Contact our support team or join our Discord community.