​
Overview

Webhooks allow your applications to receive real-time notifications when events occur in Team Inbox.

​
Event Types

  • Conversations
  • Messages
  • Contacts
  • Users
  • conversation.created
  • conversation.updated
  • conversation.assigned
  • conversation.closed

​
Webhook Setup

1

Create Webhook

POST /api/webhooks
{
  "url": "https://your-app.com/webhook",
  "events": ["message.received", "conversation.assigned"],
  "secret": "your_secret_key"
}
2

Receive Events

app.post('/webhook', (req, res) => {
  const event = req.body;
  
  // Verify signature
  if (!verifySignature(req)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Handle event
  switch(event.type) {
    case 'message.received':
      handleNewMessage(event.data);
      break;
  }
  
  res.status(200).send('OK');
});
3

Verify Signature

function verifySignature(req) {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === expected;
}

​
Payload Example

{
  "id": "evt_123",
  "type": "message.received",
  "created_at": "2025-11-29T10:30:00Z",
  "data": {
    "message": {
      "id": "msg_456",
      "conversation_id": "conv_789",
      "from": "+1234567890",
      "text": "Hello, I need help",
      "type": "text",
      "timestamp": "2025-11-29T10:30:00Z"
    }
  }
}

​
Retry Policy

Failed webhook deliveries are retried:
  • Attempt 1: Immediate
  • Attempt 2: After 1 minute
  • Attempt 3: After 5 minutes
  • Attempt 4: After 15 minutes
  • Attempt 5: After 1 hour
After 5 failures, webhook is disabled.

​
Best Practices

Verify Signatures

Always verify webhook signatures

Return Quickly

Respond 200 OK within 5 seconds

Handle Retries

Make webhooks idempotent

Monitor Health

Track webhook delivery success rate
API Reference →