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_idandstatusto 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: Bearerheader 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.
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.
Get a fresh file link
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)>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.
