Send the events of Slen to your service
Add the address of your service, choose the events it hears, keep the signing secret, and switch a webhook off or delete it.
4 min read
A webhook sends events of Slen — a hold taken, a budget nearly spent, a call that ended, a decision that is waited for — to an address of your service as they happen. This page is about the webhooks page of the console.
Where the webhooks are
Open Settings, then Webhooks. A row shows the address, whether the webhook is Active or Disabled, which projects it hears, the last four characters of its secret and how many events it is subscribed to.
The page opens for whoever has the management:read permission. Adding and changing a webhook need management:write. A webhook of all projects is added and changed only by a member who reaches every project.
Add a webhook
1. Start a new webhook
Press New webhook.
2. Choose the projects
Under Project choose All projects or one project. A webhook of one project hears the events of that project.
3. Give the address
Fill in URL: an https address on port 443, with a host name and without a login or password. An address the service cannot deliver to — one that leads into a private network, for one — is refused with webhook_url_not_allowed.
4. Choose the events
Under Events tick the events to send. At least one is needed.
5. Create the webhook
Press Create webhook.
6. Keep the secret
The window that opens shows the Signing secret once. Copy it and store it with your service: every delivery is signed with it, and your service checks the signature to know the delivery comes from Slen. The secret is not shown again.
The events of the form
The form groups the events by what they are about.
| Group | What its events report |
|---|---|
| Reservation | A hold is taken, captured, released or expired, and a call cost more than its hold |
| Budgets | budget.threshold_reached — a hold brought the use of a budget to 50 % or 80 % of its limit; budget.exceeded — to the whole limit |
| Operations | A call is authorized or refused, starts, and ends: operation.completed, operation.failed or operation.uncertain |
| Approvals | approval.requested — an execution waits for a decision; approval.decided — it was approved, rejected or expired |
operation.failedmeans the call did not happen and its hold was given back. There is one exception: a call the provider ran in the background whose hold was settled by another capture while it waited endsoperation.failedwith the reasonbackground_hold_expired, and nothing is given back.operation.uncertainmeans nobody knows how the call ended: the answer of a model node was lost, the start of a background call was not answered, or a background call stopped being asked about. Its hold stays until it expires, and the provider may have been paid. Do not repeat such a call as if it had failed.A call a flow hands to the provider to run in the background announces its end as well, with one of the three events above. One such call announces nothing: a call the provider still reports as running when its execution has waited 72 hours, by default. The execution is then closed as
failedwithparked_expired, and the operation of the call stayspending.
Slen sends more events than the form offers — of flows, connections, executions, alerts. A webhook hears them only when they are named among its events through the API.
How deliveries arrive
A delivery is a
POSTwith the event in its body, signed with the secret of the webhook.A delivery that fails is sent again later, with growing pauses.
The same event may arrive more than once. Tell the events apart by their id.
Switch off or delete a webhook
The menu in the row of a webhook holds Disable — Enable on a webhook that is off — and Delete. A disabled webhook keeps its address, events and secret, and no new event is sent to it. Delete removes it after a confirmation, and its address stops receiving events.
Webhooks and notifications
A webhook is for your service: a signed request with the event as JSON, about every event it is subscribed to, sent again until your service takes it. A notification is for people: a message in email, Telegram, Slack, Microsoft Teams or Discord about an alert or an approval, in the language of the reader, with digests and quiet hours. To tell people, set up Notifications. They do not depend on the webhooks, and an event reaches both.
Where to go next
Alerts — the alerts whose
alert.openedandalert.resolveda webhook can carry.Budgets — when a budget sends its events.
Audit log — who added, changed or deleted a webhook.
Webhooks — what a delivery carries, how to check its signature, and every event.
Notifications — tell people about alerts and approvals.