Guides
Webhooks

Webhooks

Receive real-time notifications when events happen in your avatars.

What are Webhooks?

Webhooks are HTTP callbacks that notify your server when events occur. Instead of polling our API, we push data to your endpoint.

Setting Up Webhooks

Via Dashboard

  1. Go to Dashboard > Settings > Webhooks
  2. Click Add Webhook
  3. Enter your endpoint URL
  4. Select events to subscribe to
  5. Click Save

Via API

POST /v1/webhooks
{
  "url": "https://your-server.com/webhooks/avatarium",
  "events": ["conversation.started", "message.created", "conversation.ended"],
  "secret": "your-webhook-secret"
}

Available Events

Conversation Events

EventDescription
conversation.startedNew conversation began
conversation.endedConversation completed or timed out
conversation.escalatedHuman escalation triggered

Message Events

EventDescription
message.createdNew message in conversation
message.failedMessage processing failed

Avatar Events

EventDescription
avatar.updatedAvatar settings changed
avatar.deletedAvatar was deleted

Safety Events

EventDescription
safety.escalationHuman escalation triggered
safety.topic_blockedBlocked topic detected
safety.filter_triggeredContent filter activated

Webhook Payload

All webhooks include:

{
  "id": "evt_abc123",
  "type": "message.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "conversationId": "conv_xyz789",
    "avatarId": "avt_def456",
    "message": {
      "id": "msg_ghi012",
      "role": "user",
      "content": "Hello!"
    }
  }
}

Verifying Webhooks

We sign all webhooks with your secret. Verify the signature to ensure authenticity:

const crypto = require('crypto');
 
function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
 
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
 
// In your webhook handler
app.post('/webhooks/avatarium', (req, res) => {
  const signature = req.headers['x-avatarium-signature'];
  const isValid = verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET);
 
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
 
  // Process the webhook
  const event = JSON.parse(req.body);
  console.log('Received event:', event.type);
 
  res.status(200).send('OK');
});

Retry Policy

If your endpoint fails to respond with 2xx:

  1. Immediate retry – After 5 seconds
  2. Second retry – After 30 seconds
  3. Third retry – After 5 minutes
  4. Final retry – After 1 hour

After 4 failures, the webhook is marked as failing. We'll notify you via email.

Best Practices

  1. Respond quickly – Return 200 immediately, process async
  2. Handle duplicates – Use the event id to deduplicate
  3. Verify signatures – Always validate webhook authenticity
  4. Use HTTPS – Required for production webhooks
  5. Monitor failures – Set up alerts for webhook errors

Testing Webhooks

Use our test endpoint to simulate events:

curl -X POST https://api.avatarium.ai/v1/webhooks/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "message.created", "webhookId": "wh_abc123"}'

Or use the Send Test button in Dashboard > Webhooks.

Go to Dashboard → (opens in a new tab)

Custom 3D ModelsAnalytics