Table of contents

Configure a webhook to receive alerts

Application Security provides a webhook push notification for security events. The webhook integration is a flexible and easy way for getting the security events detected by Application Security integrated with your preferred log event handling, for example with your preferred SIEM. Once properly configured and activated, the webhook integration posts security events in batches to the http endpoint you configured. Configuring the webhook integration requires:

  1. A server that will be receiving the security events posted by Application Security
  2. The webhook integration configuration in Application Security

Configure the webhook integration in Application Security

  1. In the Application Security left menu, click Integration icon.
  2. Click Add Integration.
  3. Select Webhook from the pop-up window.

    Webhook Configuration

  4. In the Add Integration to Account window, fill in the fields:

    • Hint: A hint you can use to help you remember what endpoint was used to integrate Application Security with your server. For security reasons, your webhook details will be hidden once the integration is added.
    • Minimum Reported Severity: The events severity that will be posted to the endpoint. The severity can be one of low, medium and high.
    • Webhook URL: The URL for the endpoint where Application Security will be posting the security events

      Webhook Configuration

  5. Select Add New Custom Headers, if required.

    When custom headers are configured, the headers' key value pairs are included in each post message sent to the configured URL. The custom headers can be used, for example, to include an authorization key that the server can use to authenticate and authorize the post message to the server. To configure customer headers:

    • key: The header's name
    • value: The header's value

      Webhook Custom Headers

  6. Select Add Integration.

You've completed adding your webhook integration to Application Security. However, at this point the webhook integration is in pending state, as indicated by the integration status:

Pending Integration

In order to avoid configuration mistakes negatively impacting the webhook destination, and for security reasons, the integration link needs to be confirmed, in order to change state from pending to idle. Confirming the integration link ensures the URL destination was configured properly and that the person configuring the webhook link owns the webhook destination. When first adding the webhook integration, Application Security sends a notification with a confirmation link, to the configured webhook URL. The simple message looks like:

Confirmation Link

To confirm the integration link, a message needs to be sent to the confirmation link URL. For example, the URL could be pasted in a browser, or curl could be used to connect to the confirmation link. Once Application Security gets the request to the confirmation link, the webhook integration link is activated and the integration state changes from pending to idle.

Idle Integration

Now that the webhook integration is activated, the integration can be tested. By selecting the webhook integration, the integration details panel opens. In the details panel, there is a Test Integration button. Application Security provides te Test Integration to validate the events can be properly received by the webhook server. Select the Test Integration button. A message similar to the following message should be received by the server:

Test Integration

You've completed integrating Application Security with your webhook! When a new alert is generated, it will be posted to your endpoint.

Batch of security events

The security events can be raised at different rates and in order to ensure the server doesn't get overloaded with post requests, the security events are posted in batches. The events are sent every 5 seconds in batches of up to 500 events in a single message. Note that batches are sent sequentially, that is, a batch is sent after the previous batch receives the http response from the server. For example: - 750 security events are raised. After 5 seconds, a first batch of 500 events is posted to the server. The server takes 6 seconds to respond. Meanwhile, another 500 events are raised. Upon receiving the server response, a batch of 500 events is sent and immediately upon receiving the server response, another batch of 250 events is sent.

Webhook integration and server response codes

Application Security posts security events to the configured URL using an HTTP POST. In turn, the server can respond to the post with the standard response codes. The Application Security webhook integration doesn't cache or throttle the security events and deals with the HTTP response codes as described below:

  • 200: The expected, normal response code. No action is taken.
  • 5xx: Indicates server failures. The 5xx responses are ignored and the security events from the Post message are not resent.
  • 401 and 403: Indicate authentication or authorization issues related to the request. Results in the webhook integration being disabled.
  • other 4xx codes: Indicates server failures. The 4xx responses are ignored and the security events from the Post message are not resent.