Webhook notifications

Webhooks send near-real-time notifications to your application from Web Security Analytics (WSA) when all alert conditions are met and triggers an alert. Previously, the only way to receive alert notifications was through email. Now you can integrate webhooks directly into your applications for a more efficient experience. This automation eliminates the need to manually input data from the service sending the alert and the receiving application.

Create a webhook alert integration

1. Click the alerts icon, then select the Settings tab.
2. In Send alerts to, click Add webhook endpoint (the first time you do this), or click any existing webhooks and then click Add webhook endpoint.
3. Name your webhook and enter your application’s endpoint.
   For example, https://www.example.com or https://www.example.com:8080/path if you have a port.
4. Add your secret token if your application requires one.
5. Click Save. You'll receive a sample alert to test the connection. If you don't see the sample alert from the new integration, check your settings and try again.
6. Once your webhook exists, click the webhook and select its checkbox.

Manage existing webhooks

Associate an existing webhook with an alert

1. Click the alerts icon, then select the Settings tab.
2. In Send alerts to, click your webhooks and select the checkbox of any webhook endpoint you want to associate with the alert.
3. Click Apply.

Remove webhook association

1. Click the alerts icon, then select the Settings tab.
2. In Send alerts to, click your webhooks and deselect the checkbox of any webhook endpoint you no longer want to associate with an alert.
3. Click Apply.

Edit webhooks

1. Click the alerts icon, then select the Settings tab.
2. In Send alerts to, click Manage webhooks, then click the edit icon for the webhook you want to edit.
3. Change the contents of any field, or expand the Associated alerts to .
4. Click Save.

Deleting webhooks

Note: Webhooks can only be deleted when they do not have any alerts connected to them. Remove all alerts connected to webhook URLs before you try to delete it.

1. Click the alerts icon, then select the Settings tab.
2. Remove the webhook association.
3. In Send alerts to, click your webhooks and then click Manage webhook endpoints.
4. Click the trash can icon for the webhook endpoint you want to delete.
5. Confirm you want to delete the webhook.

Tip: If you forget to remove the alert associations before you try to delete your webhook, you can access any associated alerts through the confirmation screen. Just expand the Associated alerts, and click into each one and then follow Remove webhook associations from step 2 onward.

Request body example

This describes the POST body sent from the webhook alert to your application.

Example

POST alerts/1ad487a8-ad4f-4d30-adfa-7a10f39074a5_4 HTTP/1.1
Host: customer-webhook-service.com
Content-Type: application/json
Akamai-Webhook-Signature: 123456ab7890cde0f98ghijk7lmno654-pq32r123s4567t89uvw0x78765y4fz3
Idempotency-Key: 987e6543-2f10-1234-5678-9012345678b9
Content-Length: 462 
 
{
  "status": "Cleared",
  "timestamps": {
    "detectedAt": 1692200000,
    "lastSeenAt": 1692201000,
    "stoppedAt": 1692202000
  },
  "account": {
    "name": "Example Corporation",
    "id": "ABC-1234"
  },
  "name": "My Alert"
  "description": "A high volume of non-mitigated requests containing web application exploits that could highly impact the customer origin.",
  "portalLink": "https://control.akamai.com/apps/securitycenter?view=web-security-analytics&alertId=c4685a2f-7b4e-4bff-91cc-498c20de7b42&cid=1&accountId=ABC-1234&startTime=1532511000000&contractTypeId=1-8BYUX"
  "idempotency": "d2c4f236-94eb-43b0-91e3-ea604cdb6e76",
  "requestTimestamp": 1692203000
}

Validate incoming request

The webhook sends a POST request to your application. It’s important to validate the HMAC-SHA256 signature of the request body and ensure the authenticity of the request coming from the webhook delivery.

Check the signature

1. Extract the signature from the incoming request’s Akamai-Webhook-Signature header.
2. Using the secret key, compute the HMAC-SHA256 signature of the request body.
3. Compare the two signatures. Discard the request if the signatures don’t match.

Secret tokens

Secret tokens are optional and verify alerts you receive come from Akamai.
Your API determines whether it requires a secret token when it’s created. You’ll take the token your system makes and use it here.

Troubleshooting

There are three main reasons why your new webhook won’t save or establish a connection:

1. The webhook URL is malformed,
2. The secret token is malformed, or
3. Something went wrong at the server and you can try again after a few minutes.

If after reformatting the webhook URL or secret token the connection continues to fail, contact your support representative.