Creating webhooks in XProtect

To create and configure a webhook, you should:

  1. Create the webhook URL.
  2. Create a webhook in Management Client.
  3. Create a rule to trigger the webhook in Management Client.
  4. Test the webhook rule and actions from XProtect (Optional).

1. Create the webhook URL

Generate or obtain the URL of the webserver or application you want to send event data to.

The URL must be static and secure as the URL will be registered in XProtect and used repeatedly to receive event data from XProtect.

If the URL of the webserver is updated, you must update the webhook URL in XProtect.

You can use http:// instead of https://, but using http:// through non-secure networks may expose event data in plain text. Using the more secure https:// is strongly recommended.

2. Create a webhook in Management Client

  1. In Management Client > Rules and Events > Webhooks, right-click Webhooks and select Add New…
  2. In Webhook Information:
    1. Name field: Enter a unique name for the webhook.
    2. Address field: Enter the URL for the webhook starting with https://. You can use http:// instead of https://, but using http:// through non-secure networks may expose event data in plain text. Using the more secure https:// is strongly recommended.
    3. Token (optional) field: Enter a token if you want to sign the webhooks requests.
  3. Click Save in the toolbar to save the new webhook.

3. Create a rule to trigger the webhook

  1. In Management Client > Rules and Events > Rules, right-click Rules and select Add Rule… to start the Manage Rule wizard at Step 1: Type of rule.
  2. In Step 1: Type of rule, specify a name and a description of the new rule in the Name and Description fields respectively.
  3. In the Select the rule type you want you to create pane, select Perform an action on <event>.
  4. In the Edit the rule description pane, click event and select an event.
  5. Click OK to create the event.
  6. Click Next to go to Step 2: Conditions.
  7. In Step 2: Conditions, apply any conditions relevant to the event you are creating.
  8. Click Next to go to Step 3: Actions.
  9. In Step 3: Actions, scroll down and select Send event info to <webhooks>.
  10. Click address on the Edit the rule description pane.
  11. Add a predefined webhook and click OK.
  12. Click Next to go to the wizard's third step.
  13. In Step 4: Stop criteria, click Finish to create the rule.

When the event you have created is triggered, an HTTP POST will be sent to the URL you configured in the Address field of the webhook specified for the event.

The payload (body) of the HTTP POST will contain event data from the event that triggered the rule.

Depending on your requirements, you may also have to set up a procedure on the webhook receiver to process the HTTP POST requests and react on the received event data.

4. Test the webhook from XProtect (Optional)

You should test the event to verify that the event triggers and performs the actions you define before utilizing the event and webhook in daily operations.

  1. Open Management Client > Rules and Events and select the event you want to test.
  2. Click Test Event to test the event.
  3. Verify that the actions defined for the event have been successfully performed, for example an email or SMS has been sent, scripts have been run, alarms have been updated, etc.