Webhooks
Send a signed request to your own URL whenever a shortcut in your workspace is created, updated, or deleted, so another system can stay in sync.
Who can use this feature?
- Workspace Owners and Admins can manage webhooks
- Available on the Business and Enterprise plans
Overview
A webhook is an HTTPS URL on your server. Lora sends it a request for every event you choose: a shortcut was created, updated, or deleted. Each request is signed, so your server can check that it came from Lora. Only shortcuts that everyone in the workspace can see are sent.
Webhooks belong to the workspace, not to a person. Every Workspace Owner and Admin sees and manages the same webhooks, and a webhook keeps working when the person who created it leaves.
You manage webhooks under Settings, then Webhooks. The list shows each webhook with its name, a green dot and Enabled while it is on, and its URL. Click a webhook to open its page: its status, URL, signing secret, events, and its delivery failures. Developers can also manage webhooks with the API.
Configure
Create a webhook
- From your workspace, click Settings in the sidebar, then Webhooks.
- Click New webhook.
- Enter a Label so you can tell webhooks apart.
- Enter the URL. It must start with
https://and use a public host name. IP addresses and private networks aren’t allowed, and Lora doesn’t follow redirects. - Copy the Signing secret and store it where your server can read it. Lora generates it for you and saves it with the webhook.
- Choose the events the webhook receives: Shortcut created, Shortcut updated, and Shortcut deleted.
- Click Create webhook.
Lora opens the new webhook’s page. You can show the secret again at any time (see Show or rotate the signing secret).
A workspace can have up to 10 webhooks, and each URL can be a webhook once.
Note: A webhook only receives events from the moment you create it. Lora doesn’t send anything for shortcuts that changed before that.
Check that requests come from Lora
Your server should verify the signature on every request. Anyone can send a request to your URL, and only a request signed with your secret comes from Lora. The webhooks page for developers has the details and code examples.
Send a test event
- Open the webhook, click the menu (…) at the top right, then Send test event.
- Choose an event and click Send test event.
Lora sends a sample event right away and shows what your server answered. A test is one try: Lora doesn’t retry it, and it doesn’t count toward disabling the webhook.
Basics
See what failed
Delivery failures on a webhook’s page lists the deliveries from the last 30 days that failed after Lora used up its retries, newest first. Deliveries that arrived are not listed, and neither are ones still waiting for a retry. Lora retries a failed delivery several times over about a day.
Click a delivery to see every attempt with your server’s status, the first part of its answer, and how long it took. The details also show the request body Lora sent. Lora hides the body when the shortcut is no longer visible to the workspace.
The result of a test event shows right away in the test dialog. It appears here only if it failed.
Resend a delivery
- In Delivery failures, click the delivery.
- Click Resend.
Lora sends the same event again, with a new signature. The event ID stays the same, so your server can recognize a duplicate. You can’t resend a delivery that is still waiting for a retry. Resend it once it has ended.
Show or rotate the signing secret
- To see the secret again, open the webhook and click the eye icon next to Signing secret. The copy icon copies it. Lora records every time a secret is shown or copied in the workspace’s audit log.
- To replace it, click the rotate icon next to the secret. The new secret signs every request right away. The old one keeps signing for 24 hours, so you can switch your server without losing events. Rotating again within those 24 hours replaces the older secret.
- If the secret leaked, check Stop the current secret immediately when you rotate. Requests signed with the old secret stop verifying at once, so switch your server first.
Change, disable, or delete a webhook
From the menu (…) on the webhook’s page:
- Edit opens a page where you change the label, the URL, or the events. If you change the URL, Lora starts the webhook over: deliveries still waiting for the old address are canceled and the failure history is cleared. The same goes for deliveries waiting for an event you remove. Lora warns you before you save.
- Disable Webhook stops all deliveries to the webhook and cancels the ones that are waiting. Enable Webhook starts again, without the events Lora skipped in between.
- Delete removes the webhook and cancels what is waiting for it.
Note: If your server answers
410 Gone, or every delivery fails for five days, Lora disables the webhook and emails the workspace’s Owners and Admins. Fix your server, then enable the webhook and send a test event.
What the messages mean
When a delivery fails, Lora says what to do next. You see the message in Delivery failures and in the delivery’s details.
| Message | What to do |
|---|---|
| Your endpoint returned 401 or 403 | Check that your server verifies requests with the current signing secret and accepts requests from Lora. |
| Your endpoint returned 404 | Check the URL path. |
| Your endpoint returned 410 Gone | Lora disabled the webhook. Enable it once your server accepts events again. |
| Your endpoint answered with a redirect | Lora doesn’t follow redirects. Use the final URL. |
| Your endpoint returned 429 | Raise the limit on your server or answer faster. Lora tries again later. |
| Your endpoint returned a 5xx status | Your server failed to handle the request. Check its logs. |
| Your endpoint did not answer within 15 seconds | Answer with a 2xx status right away and handle the event afterwards. |
| Lora could not reach your endpoint | Check that your server is online and has a valid TLS certificate. |
| DNS for this host resolves to a private address | Use a host name that resolves to a public address. |
| The host name does not resolve | Check the URL for typos and that its DNS record exists. |
| The webhook’s signing secret could not be opened | Rotate the secret. |
If your plan changes
If the workspace moves to a plan without webhooks, Lora keeps your webhooks but sends nothing to them. Settings, then Webhooks stays open, so you can read the delivery failures, disable webhooks, and delete them. To create, edit, test, or enable webhooks, upgrade to Business.
FAQ
I lost the signing secret. Open the webhook and click the eye icon next to Signing secret. If you’d rather start over, rotate it.
A webhook disabled itself.
Lora disables a webhook when your server answers 410 Gone or when every delivery has failed for five days. The webhook’s page says which. Fix your server, enable the webhook, and send a test event to check.
My server doesn’t get events for shortcuts that already exist. Webhooks only send changes from now on. Lora doesn’t send events for the past. Use the API to read your existing shortcuts.
A delivery says “Not sent”. The shortcut was private, unlisted, or deleted by the time Lora tried, or the webhook was disabled. Lora never sends the content of a shortcut the workspace can’t see.
I don’t see Webhooks in Settings. Only Owners and Admins see it, and only once webhooks are available for the workspace. Ask an Owner or Admin.