Set up and listen for webhooks

A webhook trigger event refers to a specific occurrence or action in Livepeer that prompts the webhook to send data to another system. You can learn more about the different webhook events in the Studio Webhook Core Concept section. Setting up a webhook using Node.js and Ngrok allows you to receive real-time data from Livepeer. In this guide, we’ll walk you through the steps to set up a webhook using Node.js and Ngrok to receive notifications from Livepeer.

Create a New Node.js Project

Open your terminal and create a new directory for your project:

mkdir webhook-project
cd webhook-project

Next, initialize a new Node.js project:

npm init -y

Install Dependencies

You’ll need the Express.js framework to create a web server and the body-parser middleware to parse incoming JSON data.

npm install express body-parser --save

Create an Express.js Server

Create an app.js file in your project directory and set up an Express.js server:

const express = require("express");
const bodyParser = require("body-parser");
const app = express();
const port = 3000;

// Parse JSON requests
app.use(bodyParser.json());

// Define a route to handle incoming webhook data
app.post("/webhook", (req, res) => {
  const payload = req.body;
  console.log("Received webhook data:", payload);
  // Handle the webhook data here
  res.sendStatus(200);
});

// Start the server
app.listen(port, () => {
  console.log(`Server is running on http://localhost:${port}`);
});

next, run your Express server using the following command:

node app.js

Your Express server is now running locally on http://localhost:3000.

In this case, we’re using Ngrok to expose our local server to the internet. If you’re running your server on a remote server, you can skip the next step. And for production applications, you’ll want to deploy your server to a cloud provider like Vercel or Fly.io.

Set Up Ngrok

Ngrok will create a secure tunnel to expose your local server to the internet. In a new terminal window, run the following command:

ngrok http 3000

If you don’t have Ngrok installed, you can download it here. Ngrok will provide a public URL (e.g., https://abc123.ngrok.io). You’ll use this URL as your webhook endpoint.

Set Up a Webhook in Livepeer Studio

Click the Create Webhook button and enter your Ngrok URL as the webhook endpoint. Select the an event to receive notifications for and click Create Webhook. You should now receive webhook requests for the event you selected.

Webhook Payload

Webhook payloads contain information about the event that triggered the webhook. The payload is a JSON object that contains different properties depending on the event type. The fields are defined as:

webhookId

string

The id of webhook

createdAt

string

The time when the webhook was created

timestamp

string

The time when the webhook was triggered

event

string

The event type that triggered the webhook

event_object

string

The object payload. This will be a stream/asset/task. The definitions can be found in the API reference for the specific object type.

Webhook Signatures

It is highly recommended that you verify signatures of incoming webhooks. If anyone has access to your webhook URL, they can fake events from Studio. See Webhooks.fyi for examples on best practices for webhooks.

You should verify the webhook requests that Livepeer Studio sends to your endpoints, using the request header signature. This signature will help you verify the incoming request.

Livepeer Studio will include a signature in each event’s Livepeer-Signature header.
The timestamp is prefixed by t= and the signature is prefixed by a scheme.
Schemes start with v, followed by an integer. Currently, the only valid signature scheme is v1. Livepeer Studio generates signatures using HMAC with SHA2-256.

Livepeer-Signature: t=36285904404,v1=88f3ff0fds9sf8a98vb0b096e81507cfd5c932fc17cf63a4a55566fd38da3a2d3d2

Extract from the header

Split the header, using the , character as the separator, to get a list of elements.
Split each element, using the = character as the separator, to get a prefix and value pair.

The value for the prefix t corresponds to the timestamp, and v1 corresponds to the signature (or signatures). You can discard all other elements.

t=36285904404
v1=88f3ff0fds9sf8a98vb0b096e81507cfd5c932fc17cf63a4a55566fd38da3a2d3d2

Prepare the signed payload

The signed_payload is the raw request payload. It is important to note that the JSON in the request payload includes the same timestamp from the signature header to protect against replay attacks. Compare the signature (or signatures) in the header to the expected signature.

For an equality match compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.
To protect against timing attacks: use a constant-time string comparison to compare the expected signature to each of the received signatures.

Troubleshooting Common Issues

During the setup and operation of your webhook in conjunction with Livepeer Studio, you may encounter issues that prevent your application from receiving or processing webhook events as expected. Here, we’ll outline some common issues, their solutions, and how to debug them.

Local Endpoint Configuration

Not Receiving Webhook Calls:
- Make sure that your local server is running and accessible. If using Ngrok, ensure it’s properly forwarding requests to your local server.
- Check the Ngrok’s web interface (usually accessible at http://localhost:4040) to see the list of HTTP requests being forwarded to your local server.
- Ensure that the URL you set in Livepeer Studio for your webhook endpoint is correct and is the public URL provided by Ngrok.
Error Messages in Your Server Logs:
- Look at the console logs in your terminal where your Node.js server is running to see if there are any error messages.
- Common errors might include problems parsing the request body, or errors in your route handling logic.
Verifying Webhook Signatures:
- If you are having trouble verifying the webhook signatures, double-check the logic in your verification code against the steps outlined in the guide above.
- Ensure you are correctly extracting the timestamp and signatures from the header and preparing the signed_payload string as described.

Debugging Tips

Logging:
- Add console.log statements in your Express.js route handler to output the request headers, body, and any other relevant information to the console.
- This can help you understand the data you’re receiving and identify any discrepancies between what you expect and what you’re actually getting.
Error Handling:
- Add error handling logic to your route handler to catch and log errors. This can help you identify issues in your code or configuration.
- Return meaningful error responses from your server to assist in debugging. For example, return a 400 Bad Request status code with a message indicating what was wrong with the request.
Tools:
- Use tools like Postman to send test requests to your server to ensure it’s responding as expected.
- Utilize Ngrok’s web interface to inspect the HTTP requests and responses being sent between Livepeer Studio and your server.
Livepeer Studio Dashboard:
- Check the Livepeer Studio dashboard for any error messages or logs related to your webhook configuration or the events you are subscribed to.

Getting Started

Guides

References

Set up and listen for webhooks

Create a New Node.js Project

Install Dependencies

Create an Express.js Server

Set Up Ngrok

Set Up a Webhook in Livepeer Studio

Webhook Payload

Webhook Signatures

Extract from the header

Prepare the signed payload

Troubleshooting Common Issues

Local Endpoint Configuration

Debugging Tips

Getting Started

Guides

References

​Create a New Node.js Project

​Install Dependencies

​Create an Express.js Server

​Set Up Ngrok

​Set Up a Webhook in Livepeer Studio

​Webhook Payload

​Webhook Signatures

​Extract from the header

​Prepare the signed payload

​Troubleshooting Common Issues

​Local Endpoint Configuration

​Debugging Tips

Create a New Node.js Project

Install Dependencies

Create an Express.js Server

Set Up Ngrok

Set Up a Webhook in Livepeer Studio

Webhook Payload

Webhook Signatures

Extract from the header

Prepare the signed payload

Troubleshooting Common Issues

Local Endpoint Configuration

Debugging Tips