Using Webhooks

What are Webhooks?

Webhooks allow IriSync to send real-time notifications to your application when specific events occur. Rather than requiring your application to constantly poll the API for changes, webhooks provide push-based updates delivered directly to your specified endpoint.

When an event happens in IriSync (such as content being published or a user subscribing), a webhook sends an HTTP POST request to your configured URL with information about the event. Your application can then react to these events in real-time.

Getting Started with Webhooks

// Register a new webhook programmatically
async function registerWebhook() {
  const response = await fetch('https://api.irisync.com/api/webhooks', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: 'https://your-domain.com/webhooks/irisync',
      events: ['content.published', 'user.subscribed', 'platform.connected'],
      description: 'Production webhook for content updates',
      active: true,
      secret: 'your_webhook_secret'  // Optional: If not provided, IriSync will generate one
    })
  });
  
  const data = await response.json();
  return data;
}

Webhook Event Types

IriSync webhooks can notify you about various events. Here are the main event categories:

{
  "id": "evt_123abc",
  "type": "content.published",
  "created": "2023-06-15T14:30:00Z",
  "data": {
    "content_id": "cnt_456def",
    "title": "New Blog Post",
    "status": "published",
    "published_at": "2023-06-15T14:30:00Z",
    "author_id": "usr_789ghi",
    "platforms": [
      "twitter",
      "linkedin"
    ]
  }
}

{
  "id": "evt_234bcd",
  "type": "content.updated",
  "created": "2023-06-16T09:15:00Z",
  "data": {
    "content_id": "cnt_456def",
    "title": "Updated Blog Post",
    "status": "published",
    "updated_at": "2023-06-16T09:15:00Z",
    "author_id": "usr_789ghi"
  }
}

{
  "id": "evt_345cde",
  "type": "user.subscribed",
  "created": "2023-06-17T11:00:00Z",
  "data": {
    "user_id": "usr_890jkl",
    "plan_id": "pln_123abc",
    "subscription_id": "sub_456def",
    "status": "active",
    "trial_end": "2023-07-17T11:00:00Z",
    "billing_interval": "month"
  }
}

{
  "id": "evt_456def",
  "type": "platform.connected",
  "created": "2023-06-18T13:45:00Z",
  "data": {
    "user_id": "usr_901lmn",
    "platform_id": "twitter",
    "connected_at": "2023-06-18T13:45:00Z",
    "status": "active",
    "scopes": [
      "read",
      "write"
    ]
  }
}

Webhook Security

Webhook Implementation Example

Here's a complete example of a Node.js webhook handler using Express:

// Example Express.js webhook handler
const express = require('express');
const crypto = require('crypto');
const app = express();

// Parse JSON requests
app.use(express.json({
  verify: (req, res, buf) => {
    // Store the raw body for webhook signature verification
    req.rawBody = buf;
  }
}));

app.post('/webhooks/irisync', async (req, res) => {
  try {
    // Verify webhook signature
    const signature = req.headers['x-irisync-signature'];
    const timestamp = req.headers['x-irisync-timestamp'];
    const webhookSecret = process.env.IRISYNC_WEBHOOK_SECRET;
    
    const payload = req.rawBody.toString();
    const expectedSignature = crypto
      .createHmac('sha256', webhookSecret)
      .update(`${timestamp}.${payload}`)
      .digest('hex');
    
    // Compare signatures
    if (signature !== expectedSignature) {
      console.error('Invalid webhook signature');
      return res.status(401).send('Invalid signature');
    }
    
    // Process the webhook event
    const event = req.body;
    
    switch (event.type) {
      case 'content.published':
        await handleContentPublished(event.data);
        break;
      case 'user.subscribed':
        await handleUserSubscribed(event.data);
        break;
      default:
        console.log(`Unhandled event type: ${event.type}`);
    }
    
    // Always respond with 200 to acknowledge receipt
    res.status(200).send('Webhook received');
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).send('Webhook processing failed');
  }
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

Webhook Reliability

// Handling webhook retries and idempotency
function isIdempotentlyProcessed(eventId) {
  // Check if this event has already been processed
  // This could be a database check, Redis, etc.
  return db.webhookEvents.exists(eventId);
}

function markEventProcessed(eventId) {
  // Mark this event as processed to prevent duplicate processing
  return db.webhookEvents.create({ eventId, processedAt: new Date() });
}

app.post('/webhooks/irisync', async (req, res) => {
  try {
    // Verification code...
    
    const event = req.body;
    const eventId = event.id;
    
    // Check if already processed to ensure idempotency
    if (await isIdempotentlyProcessed(eventId)) {
      console.log(`Event ${eventId} already processed`);
      return res.status(200).send('Event already processed');
    }
    
    // Process the event...
    
    // Mark as processed after successful processing
    await markEventProcessed(eventId);
    
    res.status(200).send('Webhook processed');
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).send('Webhook processing failed');
  }
});

Monitoring and Debugging

IriSync provides tools to help you monitor and debug your webhooks: