Webhooks
A webhook is a way to tell another program that something happened in Smengo: a schedule was published, a shift changed, an employee checked in, a manager decided a swap request. The moment it happens, Smengo sends a message to the URL you provide. The other program no longer has to keep asking "has anything changed?" — it finds out right away.
You only need this if you have an external system that should react to changes: your own accounting software, a reporting dashboard, a chatbot, an automation. The URL is usually given to you by the developer or contractor setting that system up.
Who can set it up
The section is available to a member with the Organization settings permission — usually the owner. You'll find it under Settings → Integrations → the Webhooks block.
The events you can pick are limited by your own permissions: if you can't see check-ins inside Smengo, you can't send them out either — those options will be unavailable.
How to add a webhook
- Click Add webhook.
- Paste the receiver URL — the person setting up your external system will give it to you. It must start with
https://. - Tick the events you want to be notified about:
- Schedule published — a manager published a month.
- Shift changed — a shift was created, updated or deleted.
- Check-in or check-out recorded — an employee checked in via the bot.
- Swap decision — a manager approved or rejected a request.
- Optionally add a description — it's just for you (for example, "BI reports").
- Click Add.
Save the secret — it's shown only once
Right after you add the webhook, a secret appears on screen — a string starting with whsec_. Every message is signed with it, so the receiving side can be sure the message really came from Smengo and not from someone else.
Copy the secret and pass it to your developer over a secure channel before closing the dialog. There is no way to see it again. If the secret gets lost, click Rotate secret and pass the new one along: for 24 hours after a rotation both work, so nothing breaks.
Check that it works
The Send test event button sends a trial message to your URL and immediately shows what your server replied. A successful reply means everything is set up correctly. If it isn't, show the reply to your developer — it says what went wrong.
Below, in Recent deliveries, you can see the last 25 messages: time, event, your server's reply, and the message itself. That's the first place to look if something is missing in the external system.
Pause and delete
- Pause — stop sending for a while. Events don't pile up while a webhook is paused: after you resume, you only get what happens from that point on.
- Delete — remove the URL entirely, along with its delivery log.
What to do if you get a disable e-mail
If your URL fails to reply successfully for about a day, Smengo stops trying and disables the webhook, and you get an e-mail. The same message appears in the webhook card as a red banner.
What to do, in order:
- Show the e-mail to your developer, or check yourself whether the receiving program is running.
- Once it's fixed, click Send test event and make sure the reply is successful.
- Switch the webhook back on with Resume.
Events that piled up while the webhook was off are not resent — the external system can read the missing data through the API. You also get an e-mail when your server explicitly replies "this URL no longer exists": in that case you need a new URL.
How webhooks differ from an API key
- An API key — the external system asks for data itself, whenever it needs it.
- A webhook — Smengo reports a change on its own, as soon as it happens.
They are usually used together: the webhook says "something changed", and the program reads the details with its API key.
For developers
Technical details — message format, headers, signature verification, the retry schedule — are in the webhooks documentation. You can pass that link to whoever sets up the receiver.