Webhooks

1. Event occurs in Vocantly
   ↓
2. Webhook service publishes event
   ↓
3. HTTP POST to your webhook URL
   ↓
4. Your server processes the event

curl -X POST https://api.vocantly.com/api/v1/apps/{appId}/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks",
    "events": ["chat.message.created", "chat.conversation.created"],
    "secret": "your-webhook-secret"
  }'

{
  "id": "webhook-delivery-id",
  "event": "chat.message.created",
  "timestamp": "2024-01-01T00:00:00Z",
  "data": {
    // Event-specific data
  }
}

{
  "id": "delivery-uuid",
  "event": "chat.message.created",
  "timestamp": "2024-01-01T00:00:00Z",
  "data": {
    "message": {
      "id": "message-uuid",
      "conversation_id": "conversation-uuid",
      "sender_id": "user-uuid",
      "sender_type": "sdk",
      "content": "Hello, world!",
      "message_type": "text",
      "created_at": "2024-01-01T00:00:00Z"
    },
    "tenant_id": "tenant-uuid",
    "app_id": "app-uuid"
  }
}

{
  "id": "delivery-uuid",
  "event": "chat.conversation.created",
  "timestamp": "2024-01-01T00:00:00Z",
  "data": {
    "conversation": {
      "id": "conversation-uuid",
      "type": "group",
      "title": "Engineering Team",
      "tenant_id": "tenant-uuid",
      "created_at": "2024-01-01T00:00:00Z"
    },
    "members": [
      {
        "user_id": "user-uuid",
        "role": "OWNER"
      }
    ]
  }
}

import crypto from 'crypto';

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

// In your webhook handler
const signature = req.headers['x-vocantly-signature'];
const isValid = verifyWebhookSignature(
  JSON.stringify(req.body),
  signature,
  webhookSecret
);

X-Vocantly-Signature: sha256=abc123...

curl https://api.vocantly.com/api/v1/apps/{appId}/webhooks/{webhookId}/deliveries \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

app.post('/webhooks', async (req, res) => {
  // Verify signature
  const signature = req.headers['x-vocantly-signature'];
  if (!verifySignature(req.body, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }

  // Process event
  const { event, data } = req.body;
  
  switch (event) {
    case 'chat.message.created':
      await handleMessageCreated(data);
      break;
    case 'chat.conversation.created':
      await handleConversationCreated(data);
      break;
    // ... other events
  }

  // Respond quickly
  res.status(200).send('OK');
});

# Start ngrok tunnel
ngrok http 3000

# Use ngrok URL in webhook configuration
# https://abc123.ngrok.io/webhooks