Link click webhooks: signed events from Brevily

Set up a link click webhook in Brevily: pick events per link, folder or organisation, verify X-Brevily-Signature in Node or Python, handle retries.

On this page
  1. How link click webhooks work
  2. Add a webhook in the console or over the API
  3. What a webhook delivery looks like
  4. Verify X-Brevily-Signature in Node and Python
  5. Webhook retries, give-up and the Deliveries log
  6. Test a webhook and rotate its secret
  7. Common questions
  8. Next steps

A link click webhook sends a signed JSON POST to your server the moment someone follows one of your Brevily links, so your CRM can flag the prospect who just opened a proposal, or your warehouse can count a campaign's clicks without polling. A webhook can also hear when a link is made, changes destination, expires, breaks, or earns an event such as a sale. This guide sets one up, checks the X-Brevily-Signature header in Node and Python, and covers retries and the delivery log.

Before you start: webhooks, folder webhooks and the number of deliveries a month depend on your plan (pricing). To add one you need the Integrations · Create permission; over the API, a key as in signing a request. Keep API errors open for the codes a call can return.

You give Brevily a public https address and choose what the webhook covers and which events it receives. From then on, each event is one signed delivery to that address.

  • One link: hears only that link. Good for a single proposal or a launch link.
  • One folder: hears the links in that folder now. A link moved out stops being sent; one moved in starts.
  • The whole organisation: hears every link. Only someone who can see every folder may add or change one; anyone else picks one link in the console, or a folder over the API.

Clicks reach you within a minute or two. Only people are sent, never bots, and a delivery never carries the visitor's IP address or user agent. A webhook hears only what happens after it was added, or after it was last turned on.

The events a webhook can receive

A new webhook receives clicks. Tick more when you add it, or later with Choose events…:

  • link.click (Clicks): a person followed the link.
  • link.created (Links made): a link was made, in the console, by the API or by an import.
  • link.updated (Destination changes): a link's destination changed, by an edit or a scheduled change going live. Other edits send nothing.
  • link.expired (Links expired): a link reached its expiry date or its click limit.
  • link.broken (Links broken): the landing check found the destination gone. Sent once each time it breaks.
  • event.reported (Events): a new event was reported: a sale, an install, a lead or your own. A repeat sends nothing, and one reported against no link reaches only the organisation's webhooks.

Add a webhook in the console or over the API

  1. Open Link setup › Integrations and, on the Webhooks card, choose Add a webhook.
  2. Enter the Webhook URL: a public https address. Private and local addresses are refused, when you add it and again before every send.
  3. To hear one link only, type it in One link only as go.example.com/back-half. Leave it blank for every link.
  4. Tick the Events it receives, then choose Add webhook.
  5. Copy the signing secret (whsec_…) into your server's environment. It's shown once.

[screenshot: Link setup › Integrations, the Add a webhook dialog with Webhook URL, One link only and Events it receives]

Over the API, the same webhook is one call. The answer is 201 with the integration and its secret, on this answer only:

bash
API=https://console.brevily.com/apiORG=EXAMPLEcurl -X POST "$API/$ORG/integrations" \  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET" \  -H "content-type: application/json" \  -d '{"url": "https://hooks.example.com/brevily", "events": ["link.click", "link.broken"]}'
  • link: one link only, as "go.example.com/autumn".
  • folder: one folder only, by its code. Not with link.
  • events: left out, the webhook receives clicks.

Change what it receives, or turn it off with "status": "DISABLED", with PATCH:

bash
curl -X PATCH "$API/$ORG/integrations/$ID" \  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET" \  -H "content-type: application/json" \  -d '{"events": ["link.click", "link.created", "link.broken"]}'

Adding a webhook takes Integrations · Create; changing, testing or turning one off takes Integrations · Edit; deleting one takes Integrations · Delete. Every route is in the Brevily API guide.

What a webhook delivery looks like

Every delivery is a POST with four headers:

  • Content-Type: application/json. The body is UTF-8 JSON on one line.
  • User-Agent: Brevily-Webhooks/1.
  • X-Brevily-Signature: t=<unix seconds>,v1=<hex>, when it was signed and the signature.
  • X-Brevily-Delivery: the event's id, the same as the body's id. Every retry carries the same one, so dedupe on it.

The body is an envelope: id, type, createdAt, and the event in data. A click, laid out for reading:

json
{  "id": "01M3VC6VN1Q9X4T7B3N8C5V0R2",  "type": "link.click",  "createdAt": "2026-10-01T09:19:58.113Z",  "data": {    "linkId": "01M397JMN3X9T4R8N3C5V0W6YZ",    "domain": "go.example.com",    "slug": "autumn",    "destinationUrl": "https://example.com/autumn-sale?utm_source=newsletter",    "clickedAt": "2026-10-01T09:19:58.113Z",    "source": "LINK",    "country": "GB",    "deviceType": "MOBILE",    "browser": "Safari",    "os": "iOS",    "referrer": "https://www.linkedin.com",    "visitorId": "7f3a9c0e5b1d42e8a6c4f9b2d0e7a315",    "variantId": null  }}
  • A field Brevily couldn't tell is null, never left out.
  • destinationUrl is where this visitor went, UTM tags included. With targeting rules or an A/B test, it's the destination this visitor got, and variantId names the variant.
  • source is LINK, or QR when the visit came from the link's QR code. referrer is the referring site's origin only.
  • visitorId tells one visitor apart for one day. Short links set no cookie, so the next day the same person has a new id. It means nothing outside your organisation.

The other link events carry linkId, domain, slug and destinationUrl, plus their own fields: createdAt; previousDestinationUrl, changedAt and via (EDIT or SCHEDULE); expiredAt and reason (DATE or CLICKS); or reason in words and foundAt. A reported event:

json
{  "id": "01M3VC6VN1Q9X4T7B3N8C5V0R2",  "type": "event.reported",  "createdAt": "2026-10-01T09:19:58.113Z",  "data": {    "eventId": "01K0000000000000000000000C",    "linkId": "01M397JMN3X9T4R8N3C5V0W6YZ",    "domain": "go.example.com",    "slug": "autumn",    "clickId": "01K0000000000000000000000K",    "event": "sale",    "source": "SERVER",    "amount": 4900,    "currency": "USD",    "customer": "cus_1042",    "properties": { "plan": "pro", "seats": 5 },    "occurredAt": "2026-10-01T09:19:58.113Z"  }}

amount is in the currency's minor unit (cents here), and null when the report had none.

Verify X-Brevily-Signature in Node and Python

Anyone can post to your address; only Brevily and you hold the secret. Check every delivery before you trust it:

  1. Read the body as raw bytes, before any JSON parsing. The signature covers the exact bytes sent.
  2. Split the header on commas into t and one or more v1.
  3. Refuse it when t is more than 300 seconds from your clock, so a captured delivery can't be replayed later.
  4. Compute HMAC-SHA256 of t, a dot and the raw body, keyed with the whole secret (whsec_ included, as text), in lowercase hex.
  5. Compare it with each v1 in constant time. One match is enough.

Node

js
import { createHmac, timingSafeEqual } from 'node:crypto';const TOLERANCE_SECONDS = 300;// header: the X-Brevily-Signature value. rawBody: the body exactly as// received (a Buffer or a string), before any JSON parsing.export function verify(secret, header, rawBody, now = Date.now() / 1000) {  let t;  const signatures = [];  for (const part of (header ?? '').split(',')) {    const i = part.indexOf('=');    if (i <= 0) continue;    const key = part.slice(0, i).trim();    const value = part.slice(i + 1).trim();    if (key === 't' && t === undefined) t = value;    else if (key === 'v1') signatures.push(value);  }  if (!/^\d{1,12}$/.test(t ?? '')) return false;  if (Math.abs(now - Number(t)) > TOLERANCE_SECONDS) return false;  const expected = Buffer.from(    createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex'),  );  return signatures.some((s) => {    const given = Buffer.from(s);    return given.length === expected.length && timingSafeEqual(given, expected);  });}

A receiver on Node's own HTTP server, in the same file. It answers first and works after, and handles each delivery once:

js
import { createServer } from 'node:http';const SECRET = process.env.BREVILY_WEBHOOK_SECRET; // the whole whsec_… valueconst handled = new Set(); // keep these in your database in productioncreateServer((req, res) => {  const chunks = [];  req.on('data', (chunk) => chunks.push(chunk));  req.on('end', () => {    const raw = Buffer.concat(chunks);    if (!verify(SECRET, req.headers['x-brevily-signature'], raw)) {      res.writeHead(401).end();      return;    }    res.writeHead(204).end(); // answer first, work after    const id = req.headers['x-brevily-delivery'];    if (handled.has(id)) return; // a retry of a delivery already handled    handled.add(id);    const event = JSON.parse(raw.toString('utf8'));    console.log(event.type, event.data.linkId);  });}).listen(8080);

With Express, a global express.json() parses the body before your handler sees it. Give the webhook route express.raw({ type: 'application/json' }) and pass req.body, a Buffer, to verify.

Python

Python 3.10 or later:

python
import hashlib, hmac, re, timeTOLERANCE_SECONDS = 300def verify(secret: str, header: str, raw_body: bytes, now: float | None = None) -> bool:    """header: the X-Brevily-Signature value. raw_body: the bytes as received."""    t, signatures = None, []    for part in (header or "").split(","):        key, sep, value = part.partition("=")        key, value = key.strip(), value.strip()        if not sep or not key:            continue        if key == "t" and t is None:            t = value        elif key == "v1":            signatures.append(value)    if t is None or not re.fullmatch(r"[0-9]{1,12}", t):        return False    if abs((time.time() if now is None else now) - int(t)) > TOLERANCE_SECONDS:        return False    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()    return any(hmac.compare_digest(expected.encode(), s.encode()) for s in signatures)

A receiver on Python's standard library, in the same file:

python
import json, osfrom http.server import BaseHTTPRequestHandler, HTTPServerSECRET = os.environ["BREVILY_WEBHOOK_SECRET"]  # the whole whsec_… valuehandled = set()  # keep these in your database in productionclass BrevilyWebhook(BaseHTTPRequestHandler):    def do_POST(self):        raw = self.rfile.read(int(self.headers.get("Content-Length", 0)))        if not verify(SECRET, self.headers.get("X-Brevily-Signature", ""), raw):            self.send_response(401)            self.end_headers()            return        self.send_response(204)  # answer first, work after        self.end_headers()        delivery = self.headers.get("X-Brevily-Delivery")        if delivery in handled:            return  # a retry of a delivery already handled        handled.add(delivery)        event = json.loads(raw)        print(event["type"], event["data"]["linkId"], flush=True)HTTPServer(("", 8080), BrevilyWebhook).serve_forever()

In Flask, request.get_data() gives the raw bytes; in Django, request.body; in FastAPI, await request.body().

Test your verify function

This published sample is a real signature over the click body above, sent on one line. Pass its own time as now, since it's older than five minutes:

js
const body = '{"id":"01M3VC6VN1Q9X4T7B3N8C5V0R2","type":"link.click","createdAt":"2026-10-01T09:19:58.113Z","data":{"linkId":"01M397JMN3X9T4R8N3C5V0W6YZ","domain":"go.example.com","slug":"autumn","destinationUrl":"https://example.com/autumn-sale?utm_source=newsletter","clickedAt":"2026-10-01T09:19:58.113Z","source":"LINK","country":"GB","deviceType":"MOBILE","browser":"Safari","os":"iOS","referrer":"https://www.linkedin.com","visitorId":"7f3a9c0e5b1d42e8a6c4f9b2d0e7a315","variantId":null}}';console.log(verify(  'whsec_4kQm8Zr2Lx9TnB6vYp3Hc7Wd1Fs5Gj0A',  't=1790846407,v1=875a4b6af85b2d82df924e644bce7359a46f52e25c7fee115dc2d09f8b3cddda',  body,  1790846407,)); // true
python
body = b'{"id":"01M3VC6VN1Q9X4T7B3N8C5V0R2","type":"link.click","createdAt":"2026-10-01T09:19:58.113Z","data":{"linkId":"01M397JMN3X9T4R8N3C5V0W6YZ","domain":"go.example.com","slug":"autumn","destinationUrl":"https://example.com/autumn-sale?utm_source=newsletter","clickedAt":"2026-10-01T09:19:58.113Z","source":"LINK","country":"GB","deviceType":"MOBILE","browser":"Safari","os":"iOS","referrer":"https://www.linkedin.com","visitorId":"7f3a9c0e5b1d42e8a6c4f9b2d0e7a315","variantId":null}}'print(verify(    "whsec_4kQm8Zr2Lx9TnB6vYp3Hc7Wd1Fs5Gj0A",    "t=1790846407,v1=875a4b6af85b2d82df924e644bce7359a46f52e25c7fee115dc2d09f8b3cddda",    body,    1790846407,))  # True

Change one character of the body and both print false. In production, leave now out.

Webhook retries, give-up and the Deliveries log

Answer any 2xx within 10 seconds and the delivery is done. Do slow work after you answer. Up to five deliveries leave at once, so they can arrive out of order: sort by the event's own time (data.clickedAt for a click) if order matters.

A failed try is tried again, six tries in all over about seven hours, on every plan:

  1. The first try, when the event is picked up.
  2. About 30 seconds after it fails.
  3. About 2 minutes later.
  4. About 10 minutes later.
  5. About 1 hour later.
  6. About 6 hours later, the last. If it fails, the delivery is given up.

Each wait varies by up to 20% either way, so a server coming back up isn't hit by every delivery at once.

  • Tried again: no answer within 10 seconds, a failed connection, a 408, 425 or 429, and every 5xx except 501 and 505.
  • Given up at once: every other 4xx, a 501 or 505, and a redirect, which is never followed. Answer a bad signature with 401: it isn't retried.

Read the Deliveries log

Open Analytics › Deliveries. It shows Deliveries this period against your plan's allowance, the Last 24 hours, what's Failing now, and Recent deliveries, filtered by All, Sent, Retrying, Gave up or Skipped (past your plan's allowance), with each try's answer and how long it took. It needs the Analytics · View permission.

[screenshot: Analytics › Deliveries with Recent deliveries and its All, Sent, Retrying, Gave up and Skipped filters]

bash
curl "$API/$ORG/integrations/deliveries?status=gaveup" \  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET"

The API lists them newest first; send the x-next-cursor header back as ?before= for the next page.

  • Each send of one event to one webhook counts once against your plan's deliveries a month. A retry isn't counted again.
  • Past the allowance and its grace, new deliveries aren't queued, and they're never sent later, even after a top-up. See usage limits and add-ons.
  • Turning a webhook off gives up every delivery it still owes, at once. Turned back on, it sends only what happens from then.
  • Deleting a webhook deletes its deliveries too. A sent or given-up delivery is kept for the number of days Recent deliveries names.

Test a webhook and rotate its secret

On the webhook's row, Send test posts a signed sample of an event it receives, on the made-up link example.test/test, and shows what your server answered. Over the API, name the event (a click when left out):

bash
curl -X POST "$API/$ORG/integrations/$ID/tests" \  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET" \  -H "content-type: application/json" \  -d '{"event": "link.broken"}'

The answer is 200 whether or not your server took it. Read ok, status and error:

json
{  "id": "01M75Q7TAZFNNJR10J9GJZ3J8Y",  "target": "https://hooks.example.com/brevily",  "ok": false,  "status": null,  "error": "Refused: unresolvable.",  "messages": []}

A test must be an event the webhook receives, and tests are limited per person: if one is refused, wait a few minutes.

Rotate the signing secret

Roll secret… on the row, or a PUT, makes a new whsec_ secret, shown once:

bash
curl -X PUT "$API/$ORG/integrations/$ID/secret" \  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET"

The old secret stops signing at once, retries of earlier deliveries included. To switch without losing any, deploy your receiver accepting either secret first, then roll, then remove the old one:

js
const ok = verify(NEW_SECRET, header, raw) || verify(OLD_SECRET, header, raw);

Common questions

Why does my Brevily webhook signature check fail when the secret is right?

Almost always the body: a framework parsed the JSON and you signed the re-serialised text instead of the raw bytes. The other cause is a server clock more than five minutes off; keep it set by NTP.

Can I send Brevily webhooks to localhost for testing?

No. A webhook accepts only a public https address; private and local addresses are refused. Use Send test against a public address, or run your verify function on the published sample signature.

Can one Brevily webhook cover a chosen set of links?

Yes: put the links in one folder and add a folder webhook over the API, since the console's dialog offers one link or the whole organisation. Folder webhooks depend on your plan (pricing). Or add a webhook for every link and filter on data.linkId in your receiver.

Are QR code scans sent to Brevily click webhooks?

Yes, as link.click events with source set to QR. A scan is counted, and sent, when the phone opens the short link, never when the camera reads the code.

How often does Brevily retry a failed webhook delivery?

Six tries in all, over about seven hours, on every plan. A timeout, a failed connection, a 408, 425 or 429, and most 5xx answers are tried again; any other 4xx, or a redirect, is given up at once.

Next steps

All developer guides

Brevily is invite-only, for now

Say what you would use it for and a person replies. Already invited? Sign in.