Webhooks

User action in Zoom → Zoom sends webhook → Your server processes → Send response

1. User types "/weather San Francisco" in Zoom Team Chat
2. Zoom sends POST request to your Bot Endpoint URL
3. Your server receives webhook with payload.cmd = "San Francisco"
4. Your server calls weather API
5. Your server sends chatbot message back with weather data

User action → Zoom webhook → Your handler → Response

{
  'x-zm-signature': 'v0=abc123...',          // Signature for verification
  'x-zm-request-timestamp': '1234567890',    // Unix timestamp
  'content-type': 'application/json'
}

{
  "event": "bot_notification",  // Event type
  "payload": {                   // Event-specific data
    "accountId": "...",
    "toJid": "...",
    "cmd": "...",
    // ... more fields
  }
}

const crypto = require('crypto');

function verifyZoomWebhookSignature(req) {
  const signature = req.headers['x-zm-signature'];
  const timestamp = req.headers['x-zm-request-timestamp'];
  const secretToken = process.env.ZOOM_VERIFICATION_TOKEN;

  if (!signature || !timestamp) {
    throw new Error('Missing signature headers');
  }

  // Construct message
  const message = `v0:${timestamp}:${JSON.stringify(req.body)}`;

  // Calculate expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secretToken)
    .update(message)
    .digest('hex');

  // Compare signatures
  if (signature !== `v0=${expectedSignature}`) {
    throw new Error('Invalid webhook signature');
  }

  return true;
}

1. Extract signature and timestamp from headers
2. Construct message: "v0:{timestamp}:{JSON body}"
3. Calculate HMAC-SHA256 with secret token
4. Compare calculated signature with header signature
5. Accept if match, reject if mismatch

app.post('/webhook', (req, res) => {
  try {
    // Step 1: Verify signature
    verifyZoomWebhookSignature(req);

    // Step 2: Extract event and payload
    const { event, payload } = req.body;

    // Step 3: Handle event
    switch (event) {
      case 'endpoint.url_validation':
        return handleUrlValidation(req, res);
      
      case 'bot_installed':
        return handleBotInstalled(payload, res);
      
      case 'bot_notification':
        return handleBotNotification(payload, res);
      
      case 'interactive_message_actions':
        return handleButtonClick(payload, res);
      
      case 'app_deauthorized':
        return handleBotUninstalled(payload, res);
      
      default:
        console.log('Unsupported event:', event);
        return res.status(200).json({ success: true });
    }
  } catch (error) {
    if (error.message.includes('signature')) {
      return res.status(401).json({ error: 'Invalid webhook signature' });
    }
    return res.status(500).json({ error: error.message });
  }
});

{
  "event": "endpoint.url_validation",
  "payload": {
    "plainToken": "xyz123abc"
  }
}

{
  "plainToken": "xyz123abc",
  "encryptedToken": "hmac_sha256(plainToken, secret_token)"
}

function handleUrlValidation(req, res) {
  const { plainToken } = req.body.payload;
  
  const encryptedToken = crypto
    .createHmac('sha256', process.env.ZOOM_VERIFICATION_TOKEN)
    .update(plainToken)
    .digest('hex');

  return res.status(200).json({
    plainToken,
    encryptedToken
  });
}

{
  "event": "bot_installed",
  "payload": {
    "accountId": "...",
    "userId": "...",
    "timestamp": 1234567890
  }
}

async function handleBotInstalled(payload, res) {
  console.log('Bot installed for account:', payload.accountId);
  
  // Optional: Initialize database, send welcome message
  // await initializeBotForAccount(payload.accountId);
  
  return res.status(200).json({ success: true });
}

{
  "event": "bot_notification",
  "payload": {
    "accountId": "...",
    "toJid": "channel@conference.xmpp.zoom.us",
    "robotJid": "bot@xmpp.zoom.us",
    "userJid": "user@xmpp.zoom.us",
    "cmd": "user's input text",
    "userName": "John Doe",
    "channelName": "Marketing",
    "timestamp": 1234567890
  }
}

async function handleBotNotification(payload, res) {
  const { toJid, cmd, accountId, userName } = payload;
  
  console.log(`${userName} sent: ${cmd}`);
  
  // Process command (e.g., call LLM)
  const response = await processCommand(cmd);
  
  // Send response
  await sendChatbotMessage(toJid, accountId, {
    body: [{ type: 'message', text: response }]
  });
  
  return res.status(200).json({ success: true });
}

{
  "event": "interactive_message_actions",
  "payload": {
    "accountId": "...",
    "toJid": "...",
    "actionItem": {
      "text": "Approve",
      "value": "approve"  // This is what you check
    },
    "messageId": "...",
    "userName": "John Doe"
  }
}

async function handleButtonClick(payload, res) {
  const { actionItem, toJid, accountId, userName } = payload;
  
  console.log(`${userName} clicked: ${actionItem.value}`);
  
  switch (actionItem.value) {
    case 'approve':
      await sendChatbotMessage(toJid, accountId, {
        body: [{ type: 'message', text: '✅ Approved!' }]
      });
      break;
    
    case 'reject':
      await sendChatbotMessage(toJid, accountId, {
        body: [{ type: 'message', text: '❌ Rejected' }]
      });
      break;
    
    default:
      console.log('Unknown action:', actionItem.value);
  }
  
  return res.status(200).json({ success: true });
}

// ✅ GOOD
app.post('/webhook', (req, res) => {
  verifyZoomWebhookSignature(req);
  // ... handle event
});

// ❌ BAD
app.post('/webhook', (req, res) => {
  // No verification - vulnerable to fake webhooks!
});

// ✅ GOOD - Respond immediately, process async
app.post('/webhook', (req, res) => {
  verifyZoomWebhookSignature(req);
  
  // Respond immediately
  res.status(200).json({ success: true });
  
  // Process asynchronously
  processWebhookAsync(req.body);
});

// ❌ BAD - Slow processing blocks response
app.post('/webhook', async (req, res) => {
  await slowLLMCall();  // May timeout!
  res.status(200).json({ success: true });
});

// ✅ GOOD - Handle unknown events
switch (event) {
  case 'bot_notification':
    return handleBotNotification(payload, res);
  default:
    console.log('Unsupported event:', event);
    return res.status(200).json({ success: true });
}

// ❌ BAD - Crash on unknown events
switch (event) {
  case 'bot_notification':
    return handleBotNotification(payload, res);
  // Missing default case - crashes on new events!
}

app.post('/webhook', (req, res) => {
  const { event, payload } = req.body;
  
  console.log(`[Webhook] ${event}`, {
    timestamp: new Date().toISOString(),
    accountId: payload.accountId,
    userId: payload.userId
  });
  
  // ... handle event
});

// ✅ GOOD
const SECRET_TOKEN = process.env.ZOOM_VERIFICATION_TOKEN;

// ❌ BAD - Hardcoded secret
const SECRET_TOKEN = 'abc123xyz';

# Install ngrok
npm install -g ngrok

# Expose local server
ngrok http 4000

# Copy HTTPS URL to Zoom Marketplace
# Example: https://abc123.ngrok.io/webhook

WEBHOOK_BASE_URL="http://YOUR_DEV_HOST:4000"

# Test with curl (will fail signature verification - expected)
curl -X POST "$WEBHOOK_BASE_URL/webhook" \
  -H "Content-Type: application/json" \
  -d '{"event":"test"}'

# Expected response: "Invalid webhook signature" (this is correct!)