Webhooks

Webhooks are part of Cliedesk Pro. A webhook sends an event to another system when something happens in Cliedesk, for example when a conversation is created. An inbound webhook works the other way: another system calls Cliedesk and starts a rule. Admins (the Manage settings permission) set up webhooks in Settings → Developer → Webhooks.

Add a webhook

1. Select Add webhook.
2. Enter the URL of the receiving system. It must be a public https:// address. Private and local addresses are refused.
3. Under Events, choose what to send. When you check every event of a group, Cliedesk also sends the new events of that group later.
4. Under Only for, you can limit the webhook to some Brand IDs, Product IDs, Channels or Conversation type IDs. Leave them empty to get everything.
5. Turn off Include personal data if the receiver should get ids and status only, without names, emails or message text.
6. Select Save. Cliedesk shows the Signing secret once. Copy it and keep it on the receiving server.

Each request has a Cliedesk-Signature header. The receiver checks it with the secret. The developer guide explains how (docs/dev/webhooks.md). When a person’s data is erased, the contact.erased event has the contact id only.

When the receiver fails

• Cliedesk tries again when the receiver does not answer, answers 429 or answers with a 5xx error. By default it tries 8 times over 24 hours. You can change Tries and Last try after on the webhook.
• After every try failed, the webhook is Paused after failures and admins get a notification. Setup Health shows it too. New events are kept while it is paused.
• Fix the receiving system, then select Resume. The kept events are sent in order.
• When the receiver answers 410 Gone, the webhook is Turned off.

Delivery log

Select Delivery log on a webhook. You see each delivery with its event, status, HTTP code and tries. Select View to see the request headers, the payload and the response. Replay sends the same payload again with the same event id, so the receiver can see it is a repeat. Replay failed (last 7 days) sends all failed deliveries of the last week again. The log is kept 30 days.

Other buttons: Send test sends a test event. New secret makes a new secret; the old one keeps working for 24 hours, so you have time to change the receiver. Pause stops sending until you resume.

Send a webhook from a rule

In a rule, add the step Send webhook. Choose the webhook by its number and write the Body as JSON with tokens, for example {"ticket": {conversation.number}, "email": {contact.email}}. Cliedesk fills in the tokens, signs the request and retries it like any other delivery.

The webhook must take the event Messages from the “Send webhook” rule step (workflow.webhook); All events is not enough. The receiver gets your body inside the normal event, under data.body, with the type workflow.webhook. When Include personal data is off, the email, name and subject tokens are empty (null).

A webhook sends what its owner (the person who added it) may see. If you may see less than the owner, you cannot change its URL, events, filters or Include personal data, and the delivery log does not show you the payloads.

Start a rule from another system

1. Make a rule with the trigger A webhook is received and save it.
2. In the trigger, select Add webhook URL. Say where the conversation is in the JSON (its ID or number, or the customer’s email) and add Fields such as total | $.order.total | number.
3. Select Add. Copy the secret that is shown once and give it, with the URL, to the other system.

A call with a wrong signature is refused. A call sent twice with the same Idempotency-Key starts the rule once. The rule’s steps can use the fields as {vars.total}. Select Calls to see the last 30 days of calls and replay one.