Quick Guide to Implementing Webhooks in Frame.io

Aug 16, 2024 • 7 minute read

Hey there, fellow Javascript devs! Ready to supercharge your Frame.io integrations with real-time updates? Let's dive into the world of webhooks and get your user-facing apps singing in perfect harmony with Frame.io.

Prerequisites

Before we jump in, make sure you've got:

A Frame.io API key (if you don't have one, hop over to your account settings and grab it)
A webhook endpoint ready to rock (psst... if you're testing locally, ngrok is your best friend)

Setting Up Webhooks

Alright, let's get our hands dirty! We'll use the Frame.io API to create a webhook. It's as easy as sending a POST request:

const axios = require('axios');

const createWebhook = async () => {
  try {
    const response = await axios.post('https://api.frame.io/v2/webhooks', {
      url: 'https://your-awesome-app.com/webhook',
      actions: ['asset.created', 'comment.created'],
      team_id: 'your-team-id'
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN'
      }
    });
    console.log('Webhook created:', response.data);
  } catch (error) {
    console.error('Error creating webhook:', error);
  }
};

createWebhook();

Configuring Webhook Events

Frame.io offers a smorgasbord of events you can listen to. From asset updates to comment creations, you've got options! Here's how you can update your webhook to listen for specific events:

const updateWebhook = async (webhookId) => {
  try {
    const response = await axios.put(`https://api.frame.io/v2/webhooks/${webhookId}`, {
      actions: ['asset.updated', 'comment.created', 'review.created']
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN'
      }
    });
    console.log('Webhook updated:', response.data);
  } catch (error) {
    console.error('Error updating webhook:', error);
  }
};

Handling Webhook Payloads

Time to catch those webhooks! Here's a quick Express.js server to get you started:

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

app.use(express.json());

app.post('/webhook', (req, res) => {
  const payload = req.body;
  console.log('Received webhook:', payload);
  // Process the webhook payload here
  res.sendStatus(200);
});

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

Verifying Webhook Signatures

Trust, but verify! Frame.io signs its webhooks, so let's make sure we're getting the real deal:

const crypto = require('crypto');

const verifySignature = (payload, signature, secret) => {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(payload)).digest('hex');
  return signature === digest;
};

app.post('/webhook', (req, res) => {
  const signature = req.headers['frame-signature'];
  if (!verifySignature(req.body, signature, 'YOUR_WEBHOOK_SECRET')) {
    return res.status(401).send('Invalid signature');
  }
  // Process verified webhook
  res.sendStatus(200);
});

Processing Webhook Data

Now that we've got our webhook data, let's do something cool with it:

app.post('/webhook', (req, res) => {
  const { action, resource } = req.body;
  
  switch (action) {
    case 'asset.created':
      console.log(`New asset created: ${resource.name}`);
      // Update UI to show new asset
      break;
    case 'comment.created':
      console.log(`New comment: ${resource.text}`);
      // Notify user of new comment
      break;
    // Add more cases as needed
  }
  
  res.sendStatus(200);
});

Error Handling and Retries

Sometimes things go sideways. No worries! Frame.io's got your back with automatic retries. But let's add some error handling to our webhook receiver:

app.post('/webhook', async (req, res) => {
  try {
    // Process webhook
    await processWebhook(req.body);
    res.sendStatus(200);
  } catch (error) {
    console.error('Error processing webhook:', error);
    // Respond with 5xx if you want Frame.io to retry
    res.status(500).send('Internal server error');
  }
});

Testing Webhooks

Before you ship it, let's make sure it works! Frame.io provides awesome tools for testing webhooks. But you can also whip up a quick script to simulate events:

const simulateWebhook = async () => {
  const payload = {
    action: 'asset.created',
    resource: { id: '123', name: 'Test Asset' }
  };
  
  try {
    await axios.post('http://localhost:3000/webhook', payload, {
      headers: {
        'Frame-Signature': 'your-test-signature'
      }
    });
    console.log('Test webhook sent successfully');
  } catch (error) {
    console.error('Error sending test webhook:', error);
  }
};

simulateWebhook();

Wrapping Up

And there you have it! You're now a Frame.io webhook wizard. 🧙‍♂️ Remember, this is just the beginning. As you get more comfortable, you can build even more complex and powerful integrations.

Keep experimenting, and don't hesitate to dive deeper into the Frame.io API docs for more advanced features. The possibilities are endless!

Happy coding, and may your integrations be ever responsive! 🚀

Additional Resources

Now go forth and build something awesome! And if you create something cool, don't forget to share it with the community. We're all in this together! 🤜🤛