Set up a webhook

A webhook belongs to the whole organisation. It receives the chosen events from all gateways and all alert rules. Add a separate webhook for each system that needs messages. You retrieve more data for a message with the REST API, as described in REST API and webhooks.

What you need

• The role Owner or Admin. Only these roles see Webhooks under Settings. You cannot add a webhook in the demo account.
• An address on the internet that receives POST requests with JSON and meets the address requirements.

Events

The table shows which events a webhook sends and when.

If a returned alert goes back to Active, no new alert.triggered follows. How alerts work explains when an alert changes status.

Every message is a POST request with JSON. The type field holds the event name and data holds the details. The order of arrival is not fixed, so use the timestamp field to decide what happened last. An example is on the webhook page under Example message. All fields are in the API reference.

The portal does not use an address in the Webhook action of an automation. It sends automation.triggered to every webhook under Settings > Webhooks that receives this event. You create an automation in Create automations.

Address requirements

The portal only sends to an address that is reachable from the internet. A blocked address receives no messages at all, and Test then shows the reason.

• The address starts with https:// or http://. Use https://, because a message over http:// crosses the internet unencrypted.
• The host is a public name or a public IP address. localhost and names ending in .local, .localhost and .internal are blocked. Private IP addresses such as 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 and 100.64.0.0/10 are blocked as well.
• Your system answers within 10 seconds with a status from 200 to 299. Answer first and process the message afterwards.
• The address does not redirect. The portal does not follow a redirect, so an answer such as 301 or 302 counts as failed.

Add a webhook

After these steps the webhook is in the list and your system knows the secret it uses to verify messages.

1. Open the webhook page

   Go to Settings > Webhooks.

2. Start adding

   Click Add webhook. The Add webhook window opens.

3. Enter the name

   In Name, enter a name that tells you which receiving system this is.

4. Enter the address

   In Address (URL), enter the full address, for example https://example.com/webhooks/modbuscloud. While Name is empty or the address does not start with http:// or https://, Create webhook stays grey.

5. Restrict the selection

   If you do not want to receive all events, clear All events. The list of events appears, with Alarm goes off already selected.

6. Select the events

   If you cleared All events, select the events your system should receive. If you do not want Alarm goes off, clear it only afterwards. When the last tick is cleared, All events is turned on again.

7. Create the webhook

   Click Create webhook. The webhook is now in the list, with Nothing sent yet below it.

8. Copy the secret

   Click Copy secret at the webhook. The secret starts with whsec_ and is now on your clipboard.

9. Save the secret

   Save the secret in the receiving system. It uses the secret to verify every message.

The secret stays with the webhook, so Copy secret also works later. You cannot change the address and events afterwards. To change them, delete the webhook with Delete and add a new one. The new webhook gets its own secret, so copy that to your system again.

Test a webhook

A test shows whether your system is reachable and accepts the message.

1. Send a test

   Click Test at the webhook. The portal immediately sends a signed message with the type webhook.test.

2. Read the result

   Read the message that appears. Test arrived gives the response of your system and the time in milliseconds. After Test did not arrive comes the reason.

If the portal receives an answer, a webhook that is on shows the time of sending and the status of the answer. A test also works when the webhook is off. A test does not count towards the failed messages and does not reset that count either.

Verify that messages are genuine

Every message is signed according to Standard Webhooks, with the secret of the webhook. The signature is in the headers webhook-id, webhook-timestamp and webhook-signature. If the signature is wrong, the message does not come from ModbusCloud or was changed on the way. Reject it.

A Standard Webhooks library does the check in one call. Give it the raw body as it arrives. If you parse the JSON first and rebuild it, the bytes change and the signature no longer matches. Example code for Node.js and Python is in the API reference.

Failed messages

If a message does not arrive, the portal tries again after 30 seconds, 2 minutes, 10 minutes, 1 hour and 6 hours. That makes six attempts in a little over seven hours. Every attempt has the same webhook-id. Store the ids you have processed and ignore a message whose id you already know.

If the sixth attempt also fails, the message counts as failed. Below the webhook, in red, is the number of messages that failed in a row. At ten, the portal turns the webhook off and it shows Off. A message that does arrive resets the count to zero.

Turn a webhook back on

After these steps a webhook that was turned off sends messages again. It never turns back on by itself.

1. Restore the system

   Restore the receiving system so that it answers in time again. If the address is wrong, add the webhook again.

2. Send a test

   Click Test at the webhook. Continue only when the message begins with Test arrived.

3. Turn on the webhook

   Turn on the switch on the right of the webhook row. Off disappears below the webhook.

Turning it on does not reset the count of failed messages. If the next message fails all six attempts, the webhook turns off again straight away. You can use the same switch to turn a webhook off yourself.