Creating webhooks

To create a webhook for a third-party system, follow these steps.

The default limit for webhook configurations is now 5. If your existing webhooks exceed 5, the extra webhooks will continue to work, but they cannot be replaced by new webhooks and can only be removed. If you require more webhooks, contact Fortinet Support.

How to create a webhook

1. In the FortiDLP Console, on the left-hand sidebar, click .
2. Under Integrations, select the Webhooks tab.
3. Click Create new webhook.
4. In the Create new webhook dialog box, do the following:
   1. In the Name field, type a name to identify the webhook in the FortiDLP Console.
   2. In the URL field, type a URL beginning with https:// to send events in the body of TLS-secured HTTP POST requests.
      

      By default, FortiDLP uses port 443 (HTTPS). You can also specify custom ports by appending a colon and the port number to the URL. For example, https://hec.example.com:8088.

   3. In the Payload format menu, select one of the following options:
      • To use FortiDLP's payload format, select JSON.
      • To use Slack's payload format, select Slack.
      • To use SentinelOne's payload format, select SentinelOne.
        

        SentinelOne webhook payloads can only be generated for detection events, and are always batched.

      • To use MS Teams' payload format, select Teams.
      • To create your own payload format, select Custom.
        

        If you select the Custom payload format, include a compatible Content-Type header at step h below.

   4. Do one of the following:
      • To be notified of detections, do the following:
        1. In the Event type menu, select Detection.
        2. If you selected Custom during step 4c, in the Template field, enter your custom payload template using the fields described in Webhook payload fields, and refer to Creating custom webhook templates for guidance.
        3. Optionally, to apply filters:
           1. In the Tags field, type one or more tags to filter detections by, separated by a space.
           2. In the Filter type menu:
              • To be notified of detections that have any of the chosen tags, select Any tag.
              • To be notified of detections that have all of the chosen tags, select All tags.
           3. In the Labels menu, choose one or more labels and do one of the following:
              • To be notified of detections that have any of the chosen labels, select Any labels.
              • To be notified of detections that have all of the chosen labels, select All labels.
           4. In the Minimum risk score field, type a minimum risk score between 0–100 to filter detections by.
      • To be notified of incidents, do the following:
        1. In the Event type menu, select Incident.
        2. If you selected Custom during step 4c, in the Template field, enter your custom payload template using the fields described in Webhook payload fields, and refer to Creating custom webhook templates for guidance.
        3. In the Receive event messages when list, select at least one of the following to be notified when:
           • An incident is created
           • An incident is resolved
           • A detection is generated by a new user (for an incident)
           • A detection is generated by a new node (for an incident).
        4. Optionally, in the Minimum risk score field, type a minimum risk score between 0–100 to filter by.
      • To be notified of audit logs, do the following:
        1. In the Event type menu, select Audit log.
        2. If you selected Custom during step 4c, in the Template field, enter your custom payload template using the fields described in Webhook payload fields, and refer to Creating custom webhook templates for guidance.
        3. In the Event types list, select one or more audit log types that you want to filter by.
   5. Optionally, to receive events in batches, do the following:
      1. Turn the Enable batching toggle on.
      2. In the Batch size field, enter the maximum number of events that can be batched in a payload.
         

         Batching is not supported for the Slack and Teams payload formats. Events are collected for a maximum of 30 seconds, and if the batch's event count is lower than the Batch size value after 30 seconds have elapsed, the batch will still be sent.

   6. Optionally, in the Token replenish rate per hour field, type a number to limit the rate at which payloads can be sent to the webhook per hour.

   For example, setting this field to 60 would enable the webhook to receive payloads no more than once per minute. Leaving the default value of 0 would allow payloads to be sent to the webhook each time a detection/incident/audit log occurs, or each time a batch of events is ready to be sent.

   7. Optionally, in the Max tokens field, type a value to limit the number of payloads sent to the webhook, considering the Token replenish rate per hour.

   Setting this field to 10 and the Token replenish rate per hour to 60 would enable FortiDLP to send no more than 10 payloads in a row to the webhook, and no more than one payload per minute on average.

   8. Optionally, to add a custom header, in the Headers field, enter the header using the format Name:Value.

   For example, Authorization:Bearer <token>

   9. Optionally, to sign payloads with a SHA265 HMAC signature, do the following:
      1. Turn the Sign payloads with a SHA265 HMAC signature toggle on.
      2. Click Copy.
         

         Secret keys will not be shown again after you save the webhook configuration. For each payload, a hash will be included in an X-Hub-Signature header.

      3. Optionally, to generate a new key, click Regenerate secret key and copy that key.
   10. Optionally, to pause a webhook, turn the Pause webhook toggle on.
       
   11. Click Create.
5. Optionally, to test the configuration:
   1. Click the table row of the webhook you created.
   2. At the bottom of the panel, click Test.
      

      This test verifies that the webhook is reachable by the FortiDLP API and does not verify if payloads are received by the third party.

6. Optionally, to view latency information and any error information, click the table row of the relevant webhook and view the information under Status.

Webhook statuses

Once you have created a webhook, it will be displayed with one of the following statuses in the FortiDLP Console, reflecting how effectively the webhook URL is receiving payloads.

Status	Description
Healthy	All payloads have been successfully delivered to the webhook URL.
Warning	Some payloads have not been delivered to the webhook URL, and there is now a backlog of payloads.
Unhealthy	There is a significant delay in the delivery of payloads, where the payload backlog is more than 12 hours old.