Webhooks

LOKE uses webhooks to notify you when events have happened

You can subscribe to any number of events to recive a HTTP POST when an event occurs.

Subscriptions are made at the organization level, so once subscribed you will recive notifications for all subscribed events in the organization.

Creating a subscription

To create a subscription you simply need to provide us with a url to send the notification to, a secret to sign the notification with, and a list of events you wish to subscribe to.

You supply your own identifying webhookRef in the url, so updating a subscription is as simple as re PUTing.

PUT /organizations/{organizationId}/webhooks/{webhookRef}

{
  "url": "https://example.com/webhook",
  "secret": "$ecret",
  "events": ["customer.created", "customer.updated"]
}

Verifying a webhook

To prevent malicious webhooks from being sent to your endpoint you should either have a secret that can't be guessed in the url, or more securely verify the signiture of the webhook.

To verify the signiture you will need to compare a SHA256 HMAC of the body with the value sent in X-Event-Signature header.

const secret = "$ecret";

function handleWebhook(req, res) {
  const signature = req.headers["x-event-signature"].slice("sha256=".length);
  const hmac = crypto.createHmac("sha256", secret);

  req.setEncoding("utf8");

  let body = "";
  req.on("data", (chunk) => {
    hmac.update(chunk);
    body += chunk;
  });

  req.on("end", () => {
    if (crypto.timingSafeEqual(Buffer.from(signature, "hex"), hmac.digest())) {
      return res.status(400).send("Invalid signature");
    }

    const data = JSON.parse(body);

    // Do something with the data

    res.write("ok");
    res.end();
  });
}

Webhook retries

We will attempt to deliver a webhook up to 5 times in the event of failure, backing off exponentially each time (10s, 20s, 40s...). A failed delivery is one that fails to return a response, or returns a status code >= 500.