> ## Documentation Index
> Fetch the complete documentation index at: https://uselora.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Lora API — Webhooks

> Get an HTTPS request when a shortcut is created, updated, or deleted in a Lora workspace. Event payloads, signature verification, retries, and how to keep your copy of the data correct.

A webhook endpoint is an HTTPS URL on your server. Lora sends it a signed `POST` request for every event you subscribe to, such as a shortcut being created.

## Requirements

* The workspace is on the Business plan or above. On Free and Basic you can't create webhook endpoints.
* You manage endpoints with an API key that carries `webhooks.read` or `webhooks.write`. Only an owner or admin of a Business workspace can add these scopes. See [Getting started](https://uselora.dev/essentials/getting-started.md#scopes). A webhook request fails with `403` and `insufficient_role` when the key's owner is no longer an owner or admin of the workspace.
* Owners and admins can also manage endpoints in the Lora app, under **Settings** and then **Webhooks**. The plan rules below apply there too. Unlike the API, the app can show a signing secret again after you create the endpoint.
* A workspace can have 10 endpoints of its own. Each URL can be an endpoint once per workspace.
* Listing and reading endpoints and deliveries, turning an endpoint off, and deleting it work on every plan that has API access. Creating an endpoint, turning one on, changing it, rotating a secret, and sending a test need the Business plan or above. Other plans get `402` with `plan_requires_upgrade`.

## Create an endpoint

```bash theme={null}
curl https://api.uselora.com/v1/webhooks \
  -H "Authorization: Bearer lora_sk_xxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6a2f6e0c-4a0f-4b8e-9d3b-2a1f5d7c9e11" \
  -d '{
    "url": "https://example.com/hooks/lora",
    "description": "Sync to the intranet",
    "events": ["shortcut.created", "shortcut.updated", "shortcut.deleted"]
  }'
```

The response is the endpoint plus its signing secret:

```json theme={null}
{
  "id": "wh_0198f2a4-7c1b-7d3e-9a52-3f6b1c2d4e5f",
  "url": "https://example.com/hooks/lora",
  "description": "Sync to the intranet",
  "events": ["shortcut.created", "shortcut.updated", "shortcut.deleted"],
  "enabled": true,
  "secret": "whsec_your_signing_secret"
}
```

The response is shown trimmed to the fields used here. The reference lists all of them.

> [!WARNING]
>
> The API returns the secret only when you create the endpoint or rotate its secret. No later API request returns it. Store it when you receive it.

A successful create returns `201`.

The `Idempotency-Key` header is optional. Lora keeps the key for 24 hours, per workspace and API key. Send the same key and the same body again, for example after a timeout. The response is then `200` with the endpoint the first request created, without the secret. If you lost the secret, [rotate it](#rotate-the-secret), or show it again in the Lora app. The same key with a different body returns `409` with `idempotency_key_reused`.

Other errors on create:

| Status | Code | When |
| - | - | - |
| 400 | `url_not_allowed` | The URL breaks the [URL rules](#endpoint-urls). The `reason` field names the rule. |
| 402 | `quota_exceeded` | The workspace already has 10 endpoints. |
| 402 | `plan_requires_upgrade` | The workspace is below the Business plan. |
| 409 | `url_in_use` | The URL is already an endpoint of the workspace. |

An endpoint receives only events created after the endpoint exists. Lora does not send events for the past. The same holds when you turn an endpoint on again, and for an event you add to its `events` list.

To check your receiver without waiting for a change, call `POST /v1/webhooks/{id}/test`. The body is optional and takes an `event` type, `shortcut.created` by default.

Lora sends a sample event, signed like a real one. The event's ID starts with `evt_test_`. The response is the delivery with its attempt, so you see your receiver's status and the start of its response. A test is one try with no retries. It goes to an endpoint that is turned off too, and it never counts toward [auto-disable](#when-an-endpoint-keeps-failing).

`GET /v1/webhooks/sample?event=shortcut.created` returns a sample event without sending it. Its ID starts with `evt_sample_`.

Test sends and resends are rate limited: 10 test sends a minute per endpoint, and 30 resends a minute per workspace. A request over the limit gets `429` with a `Retry-After` header, as described in [Rate limits](https://uselora.dev/essentials/rate-limits.md#when-you-hit-the-limit).

## Events

| Event | Sent when |
| - | - |
| `shortcut.created` | A shortcut that everyone in the workspace can see is created (`reason`: `inserted`), or an existing shortcut becomes visible to them (`reason`: `became_visible`). |
| `shortcut.updated` | A shortcut is updated in your workspace. This event has no `reason`. |
| `shortcut.deleted` | A shortcut that everyone in the workspace can see is deleted (`reason`: `removed`), or it stops being visible to them because it became private or unlisted (`reason`: `became_hidden`). |

Events describe the shortcuts that every workspace member can see, which are the shortcuts with visibility `WORKSPACE`. Private and unlisted shortcuts never produce an event. If a shortcut changes from visible to private or unlisted, you get `shortcut.deleted` with `became_hidden`. If it changes back, you get `shortcut.created` with `became_visible`.

Lora combines changes that happen in quick succession:

* Several edits of one shortcut become one `shortcut.updated`.
* A shortcut that is created and deleted within seconds may produce no event.

### The request

Every request is a `POST` with a JSON body and these headers:

| Header | Value |
| - | - |
| `content-type` | `application/json` |
| `user-agent` | `Lora-Webhooks/1.0 (+https://uselora.dev)` |
| `webhook-id` | The event's ID, such as `evt_0198f2a4-7c1b-7d3e-9a52-3f6b1c2d4e5f`. |
| `webhook-timestamp` | When this attempt was sent, in Unix seconds. |
| `webhook-signature` | `v1,` and a base64 signature. See [Verify the signature](#verify-the-signature). |

The body has these fields:

| Field | Description |
| - | - |
| `id` | The event's ID, starting with `evt_`. It equals the `webhook-id` header. Every event has its own ID. |
| `event` | `shortcut.created`, `shortcut.updated`, or `shortcut.deleted`. |
| `reason` | Why the event was sent. Present on `shortcut.created` and `shortcut.deleted`. |
| `createdAt` | When Lora recorded the event, ISO 8601. |
| `data` | The shortcut, as it was when Lora recorded the event. For `shortcut.deleted`, only its `id`. |

For `shortcut.created` and `shortcut.updated`, `data` has these fields of the shortcut object in the shortcuts API: `id`, `slug`, `url`, `destination`, `title`, `description`, `visibility`, `archived`, `expiresAt`, `passwordProtected`, `folderId`, `additionalFolderIds`, `tagIds`, `aliases`, `createdAt`, and `updatedAt`. Other fields of the shortcut object, such as click counts, are not sent. `additionalFolderIds` lists only the folders that everyone in the workspace can open.

`shortcut.deleted` carries no previous content. A later read of that shortcut through the API returns `404` or `403`. That is expected.

```json shortcut.created theme={null}
{
  "id": "evt_0198f2a4-7c1b-7d3e-9a52-3f6b1c2d4e5f",
  "event": "shortcut.created",
  "reason": "inserted",
  "createdAt": "2026-01-15T09:30:05.000Z",
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "slug": "handbook",
    "url": "https://app.uselora.com/acme/short/handbook",
    "destination": "https://example.com/handbook",
    "title": "Team handbook",
    "description": "An example shortcut, sent with a test event.",
    "visibility": "WORKSPACE",
    "archived": false,
    "expiresAt": null,
    "passwordProtected": false,
    "folderId": "0a1b2c3d",
    "additionalFolderIds": [],
    "tagIds": [],
    "aliases": ["team-handbook"],
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z"
  }
}
```

```json shortcut.updated theme={null}
{
  "id": "evt_0198f2b9-12aa-7c40-8e11-5a0b9d7c3e21",
  "event": "shortcut.updated",
  "createdAt": "2026-01-16T14:02:13.000Z",
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "slug": "handbook",
    "url": "https://app.uselora.com/acme/short/handbook",
    "destination": "https://example.com/handbook",
    "title": "Team handbook 2026",
    "description": "An example shortcut, sent with a test event.",
    "visibility": "WORKSPACE",
    "archived": false,
    "expiresAt": null,
    "passwordProtected": false,
    "folderId": "0a1b2c3d",
    "additionalFolderIds": [],
    "tagIds": ["a1b2c3d4"],
    "aliases": ["team-handbook"],
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-16T14:02:11.000Z"
  }
}
```

```json shortcut.deleted theme={null}
{
  "id": "evt_0198f2d0-93f4-7b02-a6d8-4c1e8f0a2b37",
  "event": "shortcut.deleted",
  "reason": "removed",
  "createdAt": "2026-01-17T08:15:42.000Z",
  "data": {
    "id": "00000000-0000-4000-8000-000000000001"
  }
}
```

The API reference describes the same payloads as schemas.

## Verify the signature

Check the signature on every request. Anyone can send a `POST` to your URL, and only a request signed with your secret comes from Lora.

Lora signs requests as the [Standard Webhooks](https://www.standardwebhooks.com) specification describes. The signature is an HMAC-SHA256 over `{webhook-id}.{webhook-timestamp}.{body}`, with your `whsec_` secret. The `standardwebhooks` and `svix` libraries verify it, and they also:

* reject a request whose timestamp is more than 5 minutes from the current time;
* compare signatures in constant time;
* accept a request when any of the signatures in the header matches. During a [secret rotation](#rotate-the-secret) the header holds two signatures.

Pass the library the raw request body, exactly as received. If you parse the JSON and serialize it again, the bytes change and the check fails.

> [tab] Node.js
>
> With the `standardwebhooks` package:
>
> ```ts theme={null}
> import express from "express";
> import { Webhook } from "standardwebhooks";
>
> const webhook = new Webhook(process.env.LORA_WEBHOOK_SECRET!);
> const app = express();
> const seen = new Set<string>(); // Use a database in production.
>
> app.post(
>   "/hooks/lora",
>   express.raw({ type: "application/json" }),
>   (req, res) => {
>     let event: { event: string };
>     try {
>       event = webhook.verify(
>         req.body,
>         req.headers as Record<string, string>,
>       ) as { event: string };
>     } catch {
>       res.status(400).send("Invalid signature");
>       return;
>     }
>
>     const eventId = req.headers["webhook-id"] as string;
>     if (!seen.has(eventId)) {
>       seen.add(eventId);
>       console.log(eventId, event.event); // Handle the event here, or queue it for a worker.
>     }
>     res.sendStatus(200);
>   },
> );
>
> app.listen(3000);
> ```
>
> With the `svix` package, change the import to `import { Webhook } from "svix";` and parse the body yourself. In `svix` 2.x, `verify` checks the signature but returns nothing, unlike `standardwebhooks`:
>
> ```ts theme={null}
> import { Webhook } from "svix";
>
> const webhook = new Webhook(process.env.LORA_WEBHOOK_SECRET!);
>
> // In the handler, in place of the `standardwebhooks` call:
> let event: { event: string };
> try {
>   webhook.verify(req.body, req.headers as Record<string, string>);
>   event = JSON.parse(req.body.toString("utf8")) as { event: string };
> } catch {
>   res.status(400).send("Invalid signature");
>   return;
> }
> ```

> [tab] Python
>
> With the `standardwebhooks` package:
>
> ```python theme={null}
> import os
>
> from flask import Flask, request
> from standardwebhooks import Webhook
>
> webhook = Webhook(os.environ["LORA_WEBHOOK_SECRET"])
> app = Flask(__name__)
> seen = set()  # Use a database in production.
>
>
> @app.post("/hooks/lora")
> def lora_webhook():
>     try:
>         event = webhook.verify(request.get_data(), dict(request.headers))
>     except Exception:
>         return "Invalid signature", 400
>
>     event_id = request.headers["webhook-id"]
>     if event_id not in seen:
>         seen.add(event_id)
>         print(event_id, event["event"])  # Handle the event here, or queue it for a worker.
>     return "", 200
> ```
>
> With the `svix` package, use `from svix.webhooks import Webhook`. Its `verify` raises on a bad signature. In `svix` 2.x it does not return the payload, so parse the body with `json.loads(request.get_data())` afterwards.

## Handle events

Respond with a `2xx` status as soon as you have stored or queued the event. Do the slow work afterwards.

### Duplicates

Delivery is at least once. Lora sends an event again when it can't confirm that you received it, and a crash on our side can also cause a repeat. Deduplicate on the `webhook-id` header. It is the same for every attempt and for a resend of the event. Do not deduplicate on the shortcut's ID: two changes to one shortcut are two events.

Zapier's instant triggers do not drop repeated events. See [Zapier](https://uselora.dev/essentials/zapier.md#events-can-arrive-twice) for a way to deduplicate in a Zap.

### Ordering and reconciliation

Events are not ordered. `data` is the state of the shortcut when Lora recorded the event, not its current state. Two things follow:

* For `shortcut.created` and `shortcut.updated`, compare `data.updatedAt` with what you have stored and ignore an older snapshot. For the latest state, fetch the shortcut through the API.
* A webhook can't tell you about an event you didn't receive. After a period when your endpoint was off or down for longer than the [retry window](#retries), list your shortcuts through the API to catch up, and do it periodically. Webhooks are not a replacement for a full sync.

### Timing

Delivery normally starts within seconds of the change. After an outage on our side, delivery resumes by itself. Lora doesn't promise a delay for that case.

## Retries

Lora sends an event as soon as it is recorded. These rules decide what happens next:

* Only a `2xx` response is a success.
* Lora doesn't follow redirects. A `3xx` response is a failure.
* The request has 15 seconds in total. That covers connecting, TLS, your response headers, and reading the start of the body. Lora reads at most the first 1 KB of the body and keeps it with the attempt.
* Any other outcome is a failure: another status, a timeout, a refused connection, or a TLS error.
* A URL that fails the [URL rules](#endpoint-urls) when Lora sends is a failure too, and nothing is sent. A URL that breaks the rules outright ends the delivery at once. A name that now resolves to a private address is retried.

After a failure Lora tries again, up to 8 attempts in all over about 27 hours:

| Attempt | Waits before it |
| - | - |
| 1 | Nothing |
| 2 | 5 seconds |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 5 hours |
| 7 | 10 hours |
| 8 | 10 hours |

Each wait varies by up to 20% either way. After a `429` or a timeout, Lora waits at least one minute. A `429` or `503` with a `Retry-After` header can ask for a longer wait, up to twice the scheduled one. After the eighth failed attempt the delivery is marked `failed` and Lora doesn't try it again.

Each attempt carries a new `webhook-timestamp` and signature, so a retry hours later still passes your 5-minute tolerance. The body and the `webhook-id` stay the same.

### Deliveries and resends

`GET /v1/webhooks/{id}/deliveries` lists the last 30 days of deliveries, newest first. You can filter by `status` and `event`. Each delivery lists its attempts with the response status, the first 1 KB of the response, and the duration.

`POST /v1/webhook-deliveries/{id}/resend` makes one more attempt for a delivery that is no longer pending. A delivery that is still waiting for a retry returns `409` with `delivery_pending`, and one with an attempt running returns `409` with `delivery_in_progress`. A resend needs the Business plan and an endpoint that is turned on: otherwise it returns `402` with `plan_requires_upgrade`, or `409` with `endpoint_disabled`, and the delivery stays as it was. The request has exactly the same body and `webhook-id` as the original, with a new timestamp and signature. A resend is a single try. It never starts the retry schedule. The response is the delivery as it stands after the attempt. It can be `skipped` when the [rules below](#change-or-remove-an-endpoint) apply, for example when the shortcut is private by now.

### When an endpoint keeps failing

* **`410 Gone`.** If your server answers `410`, Lora treats the endpoint as intentionally gone. It turns the endpoint off with `disabledReason` set to `gone` and doesn't retry that delivery. Lora emails the workspace's owners and admins.
* **Repeated failures.** Lora counts each delivery whose eight attempts all failed. It turns an endpoint off with `disabledReason` set to `failing` when all of these hold: 5 days have passed since the first such delivery, no delivery has succeeded since then, and at least 5 deliveries have failed all their attempts. One success starts the count over. Lora emails the workspace's owners and admins.

Turn an endpoint on again with `PATCH /v1/webhooks/{id}` and `{ "enabled": true }`. Lora doesn't send the events it skipped while the endpoint was off. [List your shortcuts](#ordering-and-reconciliation) to catch up.

## Rotate the secret

`POST /v1/webhooks/{id}/rotate-secret` returns a new secret. The old secret keeps signing for 24 hours, so you can deploy the new one without dropping requests. During that time every request carries two signatures, and a verifier holding either secret accepts it. Rotating again inside the 24 hours replaces the older secret.

If a secret leaked, send `{ "immediate": true }`. The old secret stops signing at once, and your receiver must switch to the new one immediately.

## Change or remove an endpoint

* Changing an endpoint's URL, turning it off, or deleting it cancels the deliveries that are still waiting. Nothing queued for the old URL is sent to the new one. A new URL also clears the failure counters. Removing an event from `events` cancels the waiting deliveries of that event. Deleting an endpoint returns `204`.
* Before each send, Lora checks that the shortcut is still visible to the workspace. If it has become private or unlisted or has been deleted since the event, Lora skips a pending `shortcut.created` or `shortcut.updated` delivery. A `shortcut.deleted` event carries only an ID and is always sent.
* If the workspace falls below the Business plan, Lora stops sending to its endpoints and doesn't send the deliveries that were waiting. You can still list, inspect, turn off, and delete endpoints, and read their deliveries. Delivery resumes when the workspace is back on Business or above.

## Endpoint URLs

An endpoint URL must meet these rules when you set it, and again before every request Lora sends:

* It uses `https://` and has no username or password.
* It uses a hostname, not an IP address.
* The hostname is not local. Lora refuses `localhost`, names that end in `.localhost`, `.local`, `.localdomain`, `.internal`, or `.home.arpa`, and names with no dot.
* When you set the URL, the hostname doesn't end in a dot. Write `example.com`, not `example.com.`.
* It uses port 443 (the default) or port 8443.
* The name resolves to public addresses only. Lora refuses the URL if any address is private, loopback, link-local, or otherwise not routable on the public internet.

Lora connects to an address that it has checked. It never follows a redirect.

When a create or an update fails, `url_not_allowed` carries a `reason` field:

| Reason | Meaning |
| - | - |
| `not_a_url` | The value is not a URL. |
| `scheme` | The URL does not use `https://`. |
| `userinfo` | The URL has a username or password. |
| `ip_literal` | The host is an IP address. |
| `host` | The host name is local, has no dot, or ends in a dot. |
| `port` | The port is neither 443 nor 8443. |
| `dns` | The name does not resolve, or the lookup takes longer than five seconds. |
| `private_address` | The name resolves to an address that is not public. |

To test a receiver on your machine, expose it through a tunnel service that gives you a public HTTPS URL.

Lora has no fixed IP addresses to allow-list. Verify the signature instead.

## Limits

| Limit | Value |
| - | - |
| Endpoints per workspace | 10 |
| Events on an endpoint | At least one |
| Endpoint URL length | 2048 characters |
| Endpoint description length | 200 characters |
| `Idempotency-Key` length | 255 characters |
| Delivery history | 30 days |
| Deliveries listed per request | 100 |

## Changes to the contract

Lora can add fields to an event at any time, without notice. Ignore fields you don't know. `data` is a fixed subset of the shortcut object of the shortcuts API, so a breaking change to one of those fields is also a breaking change to the event. A breaking change ships as a new event type. Lora never changes an existing event type in a breaking way. See [Versioning](https://uselora.dev/essentials/versioning.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.