Skip to main content
Synthra provides an event-driven webhook system for real-time notifications about session events, messages, and system activities.

​
Setup

const webhook = await agent.createWebhook({
  url: 'https://your-server.com/webhook',
  events: [
    'session.created',
    'message.sent',
    'context.compressed'
  ],
  secret: 'your_webhook_secret'
});

​
Event Types

// session.created
{
  "event": "session.created",
  "timestamp": "2024-03-08T14:30:00Z",
  "data": {
    "sessionId": "session_abc123def456",
    "userId": "user_9f8e7d6c5b4a"
  }
}

// message.sent
{
  "event": "message.sent",
  "timestamp": "2024-03-08T14:30:15Z",
  "data": {
    "sessionId": "session_abc123def456",
    "messageId": "msg_abc123def456",
    "content": "Hello, Synthra!",
    "tokens": 4
  }
}

​
Signature Verification

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

​
Express.js Example

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-synthra-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(payload, signature, webhookSecret)) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = req.body;
  console.log(`Received event: ${event.event}`);
  
  res.status(200).send('OK');
});

​
Retry Logic

Synthra automatically retries failed webhook deliveries:
  • Retry 1: After 1 minute
  • Retry 2: After 5 minutes
  • Retry 3: After 15 minutes
  • Retry 4: After 1 hour
  • Retry 5: After 6 hours

​
Managing Webhooks

// List webhooks
const webhooks = await agent.listWebhooks();

// Update webhook
await agent.updateWebhook('webhook_abc123def456', {
  events: ['message.sent', 'message.received']
});

// Delete webhook
await agent.deleteWebhook('webhook_abc123def456');
Webhook endpoints must respond with 2xx status code within 5 seconds.
Always verify webhook signatures before processing events.