openai-webhooks

OpenAI Webhooks

When to Use This Skill

• Setting up OpenAI webhook handlers for async operations
• Debugging signature verification failures
• Handling fine-tuning job completion events
• Processing batch API completion notifications
• Handling realtime API incoming calls

Essential Code (USE THIS)

Express Webhook Handler

const express = require('express');
const crypto = require('crypto');

const app = express();

// Standard Webhooks signature verification for OpenAI
function verifyOpenAISignature(payload, webhookId, webhookTimestamp, webhookSignature, secret) {
  if (!webhookSignature || !webhookSignature.includes(',')) {
    return false;
  }

  // Check timestamp is within 5 minutes to prevent replay attacks
  const currentTime = Math.floor(Date.now() / 1000);
  const timestampDiff = currentTime - parseInt(webhookTimestamp);
  if (timestampDiff > 300 || timestampDiff < -300) {
    console.error('Webhook timestamp too old or too far in the future');
    return false;
  }

  // Extract version and signature
  const [version, signature] = webhookSignature.split(',');
  if (version !== 'v1') {
    return false;
  }

  // Create signed content: webhook_id.webhook_timestamp.payload
  const payloadStr = payload instanceof Buffer ? payload.toString('utf8') : payload;
  const signedContent = `${webhookId}.${webhookTimestamp}.${payloadStr}`;

  // Decode base64 secret (remove whsec_ prefix if present)
  const secretKey = secret.startsWith('whsec_') ? secret.slice(6) : secret;
  const secretBytes = Buffer.from(secretKey, 'base64');

  // Generate expected signature
  const expectedSignature = crypto
    .createHmac('sha256', secretBytes)
    .update(signedContent, 'utf8')
    .digest('base64');

  // Timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// CRITICAL: Use express.raw() for webhook endpoint - OpenAI needs raw body
app.post('/webhooks/openai',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const webhookId = req.headers['webhook-id'];
    const webhookTimestamp = req.headers['webhook-timestamp'];
    const webhookSignature = req.headers['webhook-signature'];

    // Verify signature
    if (!verifyOpenAISignature(
      req.body,
      webhookId,
      webhookTimestamp,
      webhookSignature,
      process.env.OPENAI_WEBHOOK_SECRET
    )) {
      console.error('Invalid OpenAI webhook signature');
      return res.status(400).send('Invalid signature');
    }

    // Parse the verified payload
    const event = JSON.parse(req.body.toString());

    // Handle the event
    switch (event.type) {
      case 'fine_tuning.job.succeeded':
        console.log('Fine-tuning job succeeded:', event.data.id);
        break;
      case 'fine_tuning.job.failed':
        console.log('Fine-tuning job failed:', event.data.id);
        break;
      case 'batch.completed':
        console.log('Batch completed:', event.data.id);
        break;
      case 'batch.failed':
        console.log('Batch failed:', event.data.id);
        break;
      case 'batch.cancelled':
        console.log('Batch cancelled:', event.data.id);
        break;
      case 'batch.expired':
        console.log('Batch expired:', event.data.id);
        break;
      case 'realtime.call.incoming':
        console.log('Realtime call incoming:', event.data.id);
        break;
      default:
        console.log('Unhandled event:', event.type);
    }

    res.json({ received: true });
  }
);