Webhooks

Receive notifications when images are generated or events occur.

Overview

Webhooks notify your server when:

• Images are generated
• Usage limits are approached
• Monthly usage resets
• Account events occur

Setting Up Webhooks

Via Dashboard

1. Go to Dashboard → Settings → Webhooks
2. Enter your endpoint URL
3. Select events to receive
4. Save and test

Via API

curl -X POST https://ogimageapi.io/api/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "url": "https://yoursite.com/api/og-webhook",
    "events": ["image.generated", "usage.warning"],
    "secret": "your-webhook-secret"
  }'

Webhook Events

image.generated

Fired when an image is successfully generated.

{
  "event": "image.generated",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "request_id": "req_abc123",
    "template": "blog",
    "dimensions": {
      "width": 1200,
      "height": 630
    },
    "generation_time_ms": 145
  }
}

usage.warning

Fired when usage approaches limit (80%, 90%, 95%).

{
  "event": "usage.warning",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "current_usage": 4500,
    "quota": 5000,
    "percentage": 90,
    "plan": "pro"
  }
}

usage.limit_reached

Fired when monthly limit is reached.

{
  "event": "usage.limit_reached",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "current_usage": 5000,
    "quota": 5000,
    "plan": "pro",
    "resets_at": "2024-02-01T00:00:00Z"
  }
}

usage.reset

Fired when monthly usage resets.

{
  "event": "usage.reset",
  "timestamp": "2024-02-01T00:00:00Z",
  "data": {
    "previous_usage": 4823,
    "new_quota": 5000,
    "plan": "pro"
  }
}

Webhook Security

Signature Verification

All webhooks include a signature header:

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

Verify the signature:

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(`sha256=${expected}`)
  );
}

// Express middleware
app.post('/api/og-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-og-signature'];
  
  if (!verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(req.body);
  // Process event...
  
  res.status(200).send('OK');
});

IP Allowlist

Webhook requests come from these IPs:

• 35.192.0.0/12 (Google Cloud)
• 76.76.21.0/24 (Vercel)

Handling Webhooks

Basic Handler

// Express
app.post('/api/og-webhook', async (req, res) => {
  const event = req.body;
  
  switch (event.event) {
    case 'image.generated':
      await logImageGeneration(event.data);
      break;
    
    case 'usage.warning':
      await sendSlackAlert(`Usage at ${event.data.percentage}%`);
      break;
    
    case 'usage.limit_reached':
      await notifyTeam('OG Image limit reached!');
      break;
  }
  
  res.status(200).send('OK');
});

Async Processing

For reliability, acknowledge immediately and process async:

app.post('/api/og-webhook', async (req, res) => {
  // Acknowledge immediately
  res.status(200).send('OK');
  
  // Process async
  await queue.add('process-og-webhook', req.body);
});

// Worker
queue.process('process-og-webhook', async (job) => {
  const event = job.data;
  // Process event...
});

Retry Policy

Failed webhook deliveries are retried:

• 1st retry: 1 minute
• 2nd retry: 5 minutes
• 3rd retry: 30 minutes
• 4th retry: 2 hours
• 5th retry: 24 hours

After 5 failures, the webhook is disabled.

Testing Webhooks

Test Event

Send a test event:

curl -X POST https://ogimageapi.io/api/webhooks/test \
  -H "X-API-Key: YOUR_API_KEY"

Local Development

Use ngrok for local testing:

ngrok http 3000
# Use the ngrok URL as your webhook endpoint

Webhook Management

List Webhooks

curl https://ogimageapi.io/api/webhooks \
  -H "X-API-Key: YOUR_API_KEY"

Update Webhook

curl -X PUT https://ogimageapi.io/api/webhooks/webhook_id \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "url": "https://newurl.com/webhook",
    "events": ["usage.warning"]
  }'

Delete Webhook

curl -X DELETE https://ogimageapi.io/api/webhooks/webhook_id \
  -H "X-API-Key: YOUR_API_KEY"

Best Practices

1. Always verify signatures — Prevent spoofed requests
2. Respond quickly — Return 200 within 5 seconds
3. Process async — Don't block on webhook handling
4. Handle duplicates — Webhooks may be sent twice
5. Monitor failures — Track delivery issues