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.readorwebhooks.write. Only an owner or admin of a Business workspace can add these scopes. See Getting started. A webhook request fails with403andinsufficient_rolewhen 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
402withplan_requires_upgrade.
Create an endpoint
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, 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:
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.
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.
Events
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 aPOST with a JSON body and these headers:
The body has these fields:
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.
Verify the signature
Check the signature on every request. Anyone can send aPOST to your URL, and only a request signed with your secret comes from Lora.
Lora signs requests as the Standard Webhooks 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 the header holds two signatures.
- Node.js
- Python
With the With the
standardwebhooks package: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:Handle events
Respond with a2xx 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 thewebhook-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 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.createdandshortcut.updated, comparedata.updatedAtwith 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, 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
2xxresponse is a success. - Lora doesn’t follow redirects. A
3xxresponse 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 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.
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 apply, for example when the shortcut is private by now.
When an endpoint keeps failing
410 Gone. If your server answers410, Lora treats the endpoint as intentionally gone. It turns the endpoint off withdisabledReasonset togoneand 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
disabledReasonset tofailingwhen 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.
PATCH /v1/webhooks/{id} and { "enabled": true }. Lora doesn’t send the events it skipped while the endpoint was off. List your shortcuts 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
eventscancels the waiting deliveries of that event. Deleting an endpoint returns204. - 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.createdorshortcut.updateddelivery. Ashortcut.deletedevent 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, notexample.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.
url_not_allowed carries a reason field:
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
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.