Outbound webhooks

Push instead of poll

Rather than asking the API every few minutes whether anything happened, register an endpoint and ShortZen calls you when it does.

Webhook endpoints, by plan

Free Not included · Starter 1 · Pro 5 · Business 20

Webhook deliveries / month, by plan

Free Not included · Starter 2,000 · Pro 20,000 · Business 100,000

Registering an endpoint

On the Developer page, give a URL and pick which events it should receive. The URL must be https: plain http is refused, because a webhook body is your data crossing the internet. The URL and signing secret cannot be changed later; the events can, from the endpoint sheet.

Each endpoint gets a signing secret, shown once. Copy it into your secret store and acknowledge that you have saved it before leaving the page: we cannot show it again.

Verifying a delivery is really from us

Each delivery carries headers naming the event, a signature, and an id for this delivery:

x-shortzen-event:       link.created
x-shortzen-signature:   t=1700000000,v1=<hex hmac-sha256>
x-shortzen-delivery-id: <delivery id>

The body is a JSON envelope: the event name, the timestamp the delivery was signed at, and the event's own fields under data.

{
  "event": "link.created",
  "createdAt": 1700000000,
  "data": {
    "id": "lnk_1a2b3c4d5e6f7a8b",
    "slug": "spring-sale",
    "destinationUrl": "https://example.com/spring-sale"
  }
}

createdAt is the same value as the t in the signature header, in seconds. It is stamped per attempt rather than when the event happened, so a retry of one delivery arrives with a later createdAt than the attempt before it.

The signature is an HMAC-SHA256 over the timestamp, a full stop, and the raw request body, keyed with the endpoint's signing secret.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, header, secret) {
  const parts = header.split(',').map(p => p.split('='));
  const timestamp = parts.find(([key]) => key === 't')?.[1];
  // One v1 per signing secret still accepted: two while a rotation overlaps, so any match passes.
  const signatures = parts.filter(([key]) => key === 'v1').map(([, value]) => value);
  const expected = createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  // Constant-time compare: a plain === leaks the answer one byte at a time.
  const a = Buffer.from(expected);
  return signatures.some((signature) => {
    const b = Buffer.from(signature);
    return a.length === b.length && timingSafeEqual(a, b);
  });
}

While you rotate a signing secret, the header carries one v1 for each secret that is still accepted: t=…,v1=<new secret>,v1=<old secret>. Accept the delivery if any of them matches, as the function above does. A verifier that reads only the first v1, or only the last, rejects deliveries until you switch the secret.

• Sign over the raw body exactly as received. Parsing to JSON and re-serialising changes the bytes and the signature will not match.
• Compare in constant time.
• Reject deliveries whose timestamp is far from now, so an old captured request cannot be replayed at you.

Rotating the signing secret

Open an endpoint on the Developer page and choose Rotate secret. ShortZen starts signing with a new secret on the same endpoint, so its history, URL and events stay as they are. The new secret is shown once, like the first one: copy it into your secret store before you leave.

You choose what happens to the current secret. Keep it working for 24 hours is the default: during that day every delivery carries a signature for both secrets, so you can deploy the new one without dropping events. Stop it now is for a secret that may have leaked: deliveries are signed with the new secret only, and your receiver rejects them until you update it.

Retries and delivery history

Answer with a 2xx quickly. A non-2xx or a timeout is treated as a failure and retried automatically.

Open an endpoint to see its delivery history: one row per event, showing the attempts and how it finished. Retry is offered on failed deliveries only, without needing the original event to happen again. Pending deliveries are still in flight; successful ones are already done. History is kept for 90 days: it is useful for chasing down a recent "my webhook did not fire" report, not a permanent audit trail.

Because retries exist, your handler must tolerate seeing the same event twice. Record the x-shortzen-delivery-id header and ignore a delivery id you have already processed. It stays the same across every automatic retry of one delivery, while the signature and createdAt do not. A manual retry is a new delivery with a new id, so if you need to collapse those too, key on the fields in data as well: id for link.created, linkId with occurredAt for link.clicked, id for conversion.recorded.

When an endpoint gets auto-disabled

If an endpoint answers with a bad HTTP response (a non-2xx status, or a response your handler rejects) for 10 deliveries in a row, ShortZen marks it Needs attention and posts an in-app notification. A network-level problem on our side reaching your endpoint (a DNS failure, a timed-out connection) does not count toward that streak, so the endpoint is only auto-disabled for something genuinely wrong with it.

Step by step