Webhooks

A webhook is a way for our admin system to tell another computer system when something happens — automatically, the moment it happens.

Imagine you want a separate program (maybe an accounting tool, a warehouse system, or a Slack channel) to know every time a customer places a paid order. Instead of that program constantly asking "anything new yet?", our system simply sends it a message the instant the event occurs. That message is the webhook. The event has a name, like product.created (a product was created) or page.published (a page went live).

This page is mostly for developers

Setting up a webhook means giving it a web address that belongs to another system. You will usually do this together with a developer who is building the receiving side. This page explains it in plain terms so you understand what you are looking at, but you do not have to set one up alone.

How to open it

1. Sign in to the admin system.
2. In the left-hand menu, click Webhooks.
3. You will see a form for adding a new webhook at the top, and a table of any existing webhooks below it.

What you can do here

Understand what a webhook is made of

Every webhook has three simple parts:

• A name — a label so you remember what it is for (e.g. "Accounting sync").
• A URL — the web address of the other system that should receive the messages. It looks like https://example.com/hooks/kcms.
• A list of events — the things you want to be told about. When one of those events happens, our system sends a message to the URL.

Add a new webhook

1. In the Name box, type a short label so you can recognise it later.
2. In the URL box, paste the web address the developer gave you. It must start with https://.
3. Under Events, tick the boxes for the events you want to be notified about. You can tick several. Ticking the star (*) means all events — you will be told about everything.
4. Click Create webhook.
5. A green box appears with a signing secret — a long line of random characters. Copy it now and give it to the developer. You will never see it again after you leave this box.

The signing secret is shown only once

The signing secret is like a password that lets the receiving system check that a message really came from us and was not faked by someone else. We show it a single time, right after you create the webhook. If you lose it, you cannot look it up — you have to make a new one (see Rotate the secret below).

Turn a webhook on or off

In the table, the Status column shows a button that reads active or off.

1. Click the button to flip it.
2. active means messages are being sent. off means the webhook is paused and no messages go out, but its settings are kept.

Use "off" when you want to pause notifications temporarily without deleting the whole thing.

Rotate the secret

"Rotate" means replace the old secret with a brand-new one. Do this if you think the old secret may have leaked, or if you simply lost it.

1. In the table row, click Rotate secret.
2. Confirm when asked. The old secret stops working immediately.
3. A green box shows the new secret. Copy it and give it to the developer, who must update the receiving system to use it.

Delete a webhook

1. In the table row, click Delete.
2. Confirm when asked.
3. The webhook is removed, and its record of past deliveries is erased too. This cannot be undone.

Every field explained

Field / column	Plain-English meaning
Name	A label you choose so you can recognise the webhook later.
URL	The web address of the other system that receives the messages. Must start with https://.
Events	The list of happenings you want to be told about. Tick the star (*) for all of them.
Failures	How many recent delivery attempts failed (for example, because the other system was down). 0 is healthy. A number in an amber badge means deliveries are not getting through — tell a developer.
Status	Whether the webhook is active (sending) or off (paused). Click to flip it.
Signing secret	A one-time password that lets the receiving system confirm a message truly came from us. Shown only once, when you create the webhook or rotate the secret.

The list of events you can choose

Event name	It fires when…
product.created	A new product is added.
product.updated	An existing product is edited.
product.deleted	A product is removed.
customer.registered	A new customer signs up.
customer.updated	A customer's details change.
contact.received	Someone sends a message through the contact form.
review.submitted	A customer submits a product review.
review.approved	A review is approved for display.
campaign.created	A new campaign is created.
campaign.updated	A campaign is edited.
page.published	A page is published (made live).
*	Everything — you are told about all of the events above.

Common mistakes

Watch out for these

• Losing the signing secret. It is shown only once. Copy it straight away and hand it to the developer. If it is gone, rotate to get a new one — but that forces the developer to update their side.
• Using a web address that is not https://. The URL must be secure. A plain http:// address will be rejected.
• Ticking the star (*) by accident. The star means every event. If the other system only cares about one or two things, tick only those, or it will be flooded with messages.
• Ignoring a rising Failures number. If the Failures badge keeps climbing, the other system is not receiving messages. That usually needs a developer to look at the receiving side.
• Deleting instead of pausing. If you only need to stop messages for a while, flip the status to off. Deleting erases the webhook and its whole delivery history for good.

Still stuck?

Webhooks connect our system to someone else's, so the fix often lives on the other side. If a webhook is failing, showing an error, or you are not sure what URL or events to use, email developers@kavelsoftware.se. Include the webhook's Name and, if there is one, the number shown in the Failures column.