Receive webhooks

When an event you subscribe to happens, Easol sends an HTTPS POST request to your endpoint. The request identifies the event and the resource it relates to. Your integration decides what to do with it.

For the exact request format and delivery rules, see the webhooks reference.

Before you begin

You need:

• access to Settings in your Easol admin, with a role that includes the Create and manage webhooks permission
• a public HTTPS URL for your endpoint. Easol can't send webhooks to localhost or to a private network. To test on your own machine, use a tunnelling service, such as ngrok or Cloudflare Tunnel, that gives you a public HTTPS URL.

Choose your events

Choose the events your integration needs from the webhook events reference. Each event page describes when Easol sends it and the request body your endpoint receives.

Create the webhook

A new webhook starts turned off, so Easol sends nothing until you turn it on. You can create it before your endpoint is ready.

1. In your Easol admin, go to Settings > Developer Tools, then select the Webhooks tab.

   

2. Select Create new webhook.

3. In Endpoint URL, enter the URL of your endpoint.

4. Under Events, select the events you chose.

   

5. Select Create webhook. Easol opens the webhook's details.

6. Next to Signing secret, select the eye icon to show the secret, then copy it. Your endpoint uses the secret to check that requests come from Easol.

   

Build your endpoint

Read the raw request body and check its signature before using the event. The signature covers the exact bytes Easol sent, so parsing or changing the body first can make the check fail.

Respond with a 2xx status to acknowledge the delivery. Easol treats any other status, or no response within 30 seconds, as a failed attempt. See the retry rules for exceptions and limits. The same delivery can arrive more than once; its webhook-id stays the same across retries. Events can also arrive out of order.

Easol webhooks follow the Standard Webhooks specification, so you can check signatures with a Standard Webhooks library. The Ruby example checks the signature without one.

Each example reads the signing secret from the EASOL_WEBHOOK_SECRET environment variable. It receives requests at /webhooks/easol on port 3000. Point your public URL or tunnel at that address. The comment at the top of each example shows how to install and run it. These examples verify and log the event, then acknowledge it. Replace the logging line with your integration's event handling.

// npm install express standardwebhooks
// Save as server.mjs, then run: node server.mjs
import express from 'express';
import { Webhook } from 'standardwebhooks';

const app = express();
const webhook = new Webhook(process.env.EASOL_WEBHOOK_SECRET);

app.post('/webhooks/easol', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = webhook.verify(req.body, req.headers);
  } catch {
    return res.sendStatus(400);
  }

  console.log(event);

  res.sendStatus(200);
});

app.listen(3000);

If your framework checks every POST request for a cross-site request forgery (CSRF) token, turn that check off for your webhook route. Easol's requests don't carry a token, so the framework would reject them.

Turn on and test the webhook

1. On the webhook's details page, turn on Enabled, then select Save.
2. Perform an action in Easol that triggers one of your selected events, as described in its reference page. Easol has no button to send a test event.
3. Select the Event deliveries tab and check that the attempt shows a 2xx status.

Check deliveries

The Event deliveries tab lists every attempt to deliver an event to the webhook from the last 3 months, newest first. Older pending events are kept until delivery finishes or retries are exhausted. Select an attempt to see its status, the resource it was about, how long your endpoint took, your response and the request body Easol sent.

When an attempt fails, Easol retries it up to 9 times over roughly three days. Each retry appears as a separate attempt in the list. Internal Easol errors are also shown, but do not use up this retry limit or count towards disabling your webhook. If Easol fails before preparing the request, the attempt shows "The request could not be prepared" instead of a request body.

Fix failed deliveries

If Easol turns off your webhook

Easol turns off a webhook that keeps failing: when every attempt over more than 3 days has failed, with at least 10 failed attempts. It also turns off a webhook straight away if your endpoint responds with 410 Gone. The webhook then shows as Disabled on the Webhooks tab. Easol doesn't email you.

To start receiving events again:

1. Fix the problem with your endpoint.
2. On the webhook's details page, turn on Enabled, then select Save.
3. Catch up on the events you missed.

Catch up on missed events

Easol doesn't resend an event once its retries have run out, or events that happened while the webhook was turned off. Use the relevant resource's API endpoints to retrieve its current details. See the API reference.

Replace the signing secret

Replace the secret if it might have been exposed, for example if it was committed to a code repository. The old secret stops working as soon as you confirm. Until you give your endpoint the new secret, it rejects Easol's requests and those deliveries fail, so have your endpoint's settings ready before you start.

1. On the webhook's details page, select Roll secret, the arrows icon next to Signing secret.
2. Select Confirm.
3. Copy the new secret and update your endpoint with it.

Easol retries failed deliveries for roughly three days. Events whose retries run out before you update your endpoint aren't sent again. To find them, see Catch up on missed events.

Change or delete a webhook

To change the endpoint URL or events, or to turn the webhook off, edit them on the webhook's details page and select Save.

To delete a webhook, go to the Webhooks tab, open the menu at the end of the webhook's row and select Delete. Easol stops sending it events and deletes its delivery log.