Using Oleon

Webhooks

Call your own systems when something happens in a project, and check each call came from Oleon.

A webhook is a URL on your own server that Oleon calls when something happens in a project — for example, when a contact export is ready to download. Use it to pull the file into a CRM, start a job, or post to your team's chat.

Open the project's Settings, then Webhooks under Automation. Anyone who can see the project's contacts can see the list; creating or changing one needs permission to change contacts. A project can have 10 webhooks.

Create a webhook

Press Add webhook and fill in:

  • Name: what it is for, like CRM sync.
  • Events: what makes Oleon call it. Today these are contact exports: Export ready, Export had no contacts and Export failed.
  • Request: the method (POST or GET) and an https:// URL on the standard port (443). The URL can't contain a query string: add those values as parameters instead. A POST sends the event as a JSON body; a GET has no body and adds event, event_id, run_id and status to the query string.
  • Timeout: how long Oleon waits for your server, between 1,000 and 10,000 ms.
  • Headers and Query parameters: anything your server needs, such as an API key. Add auth header starts an Authorization: Bearer header for you. Header and parameter values are stored encrypted and shown masked. If a webhook's stored values can no longer be read, its editor asks you to enter them again.

Oleon sets Content-Type, Host, Content-Length, Connection, Transfer-Encoding and every X-Oleon-* header itself, so a webhook can't set those. The URL must be a public https:// address, with no user name or password in it.

Keep the signing secret

When a webhook is created, Oleon shows its signing secret once. Copy it to your server straight away — it can't be shown again. If it is lost or leaked, choose Rotate secret from the webhook's menu: a new secret is made and the old one stops working.

Check a call came from Oleon

Every request carries X-Oleon-Event, X-Oleon-Delivery, X-Oleon-Timestamp (Unix seconds) and X-Oleon-Signature: v1= followed by the hex HMAC-SHA256, keyed with the whole signing secret (including whsec_), of:

  • POST: the timestamp, a ., and the raw request body, exactly as received.
  • GET: the timestamp, a ., and the query string as received (everything after ?).

Compare it in constant time, and ignore requests whose timestamp is more than five minutes old.

JavaScript
import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.OLEON_WEBHOOK_SECRET; // whsec_...
const app = express();

// Keep the raw body: the signature is over the exact bytes Oleon sent.
app.post("/oleon", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.get("X-Oleon-Timestamp");
  const signature = req.get("X-Oleon-Signature") || "";
  const expected = "v1=" + crypto
    .createHmac("sha256", SECRET)
    .update(`${timestamp}.${req.body.toString("utf8")}`)
    .digest("hex");

  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
  const valid = signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  if (!fresh || !valid) return res.status(401).end();

  const event = JSON.parse(req.body.toString("utf8"));
  // Answer quickly; download event.data.download_url afterwards.
  res.status(204).end();
});

Answer with any 2xx within the webhook's timeout. Anything else is retried after about 10 seconds, 1 minute and 5 minutes. The event's id is the same on every retry and redelivery, so use it to ignore duplicates.

An export.ready event carries data.file_id and data.download_url, a link that works for 24 hours. To download the file later, ask for a new link while the file is still kept. Sign the request with the secret of one of the project's webhooks that is enabled and subscribed to an export event:

POST https://<your Oleon API>/v4/webhooks/exports/files/<file_id>/link
X-Oleon-Webhook-Id: <the webhook's id>
X-Oleon-Timestamp: <now, in Unix seconds>
X-Oleon-Signature: v1=<hex HMAC-SHA256(secret, timestamp + "." + file_id)>
JavaScript
import crypto from "node:crypto";

async function freshLink(fileId) {
  const timestamp = String(Math.floor(Date.now() / 1000));
  const signature = "v1=" + crypto
    .createHmac("sha256", process.env.OLEON_WEBHOOK_SECRET)
    .update(`${timestamp}.${fileId}`)
    .digest("hex");
  const response = await fetch(`${process.env.OLEON_API}/v4/webhooks/exports/files/${fileId}/link`, {
    method: "POST",
    headers: {
      "X-Oleon-Webhook-Id": process.env.OLEON_WEBHOOK_ID,
      "X-Oleon-Timestamp": timestamp,
      "X-Oleon-Signature": signature,
    },
  });
  if (!response.ok) throw new Error(`Oleon answered ${response.status}`);
  return response.json(); // { file_id, file_name, url, expires_at }
}

It answers 401 when a header is missing, the timestamp is more than five minutes off or the signature doesn't match; 404 when the file is gone (expired, empty or failed); and 429 after 30 requests a minute.

See what was sent

Press a webhook to open its delivery log: every call, its event, the status code your server answered with, how long it took and how many attempts it needed. Open a row to read the response or the error, and press Redeliver to send it again.

A one-off export from the Export contacts window calls your webhooks only when Send to webhooks is ticked.

Send test in the webhook's menu sends a webhook.test event, so you can check your server before a real one happens. It can be sent 5 times a minute per webhook.

A disabled webhook keeps its settings and log, and is not called until it is enabled again.