Receiving webhook deliveries

To test your webhook locally, you can use a webhook proxy URL to forward webhooks from IBM Storage Insights to your computer. You can use any of the third-party tools such as Postman, RequestBin, or smee.io to test the webhook payload. This task uses smee.io as an example to provide a webhook proxy URL and forward webhooks.

Important: The examples and steps that are provided in this page are meant to be illustrative and may not reflect the exact workflow in all situations. For specific use cases, consult the official documentation or support resources of respective third-party tools.

Get a webhook proxy URL

  1. In your browser, navigate to https://smee.io/.

    smee.io is just an example. You can use any of the third-party webhook testing tools as per your need.

  2. Click Start a new channel.
  3. Copy the full URL under Webhook Proxy URL. You need to use this URL in the following setup steps:

Forward webhooks

  1. If you have not installed smee-client already, run the following command in your terminal:
    npm install --global smee-client
  2. To receive forwarded webhooks from smee.io, run the following command in your terminal. Replace WEBHOOK_PROXY_URL with your webhook proxy URL from earlier.
    smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000

    You must see output that looks like this, where WEBHOOK_PROXY_URL is your webhook proxy URL:

    Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
    Note: The path is /webhook and the port is 3000. You need these values later when you write code to handle webhook deliveries.
  3. Keep this running while you test out your webhook. When you want to stop forwarding webhooks, enter Ctrl+C.

Create a webhook

Create a webhook in your IBM Storage Insights. For URL, use your webhook proxy URL from earlier. For more information, see Creating a webhook.

Write code to handle webhook deliveries

To handle webhook deliveries, you need to write code that does the following actions:
  • Initialize your server to listen for requests to your webhook URL
  • Read the HTTP headers and body from the request
  • Take the needed action in response to the request

You can use any programming language that you can run on your server.

The following examples print a message when a webhook delivery is received. However, you can modify the code to perform other action, such as sending a Slack message.

JavaScript example:

This example uses Node.js and the Express library to define routes and handle HTTP requests. This example requires your computer to run Node.js version 12 or greater and npm version 6.12.0 or later.

Install dependencies

To use this example, you must install the express library in your Node.js project. For example:
npm install express

Write the code

Create a JavaScript file with the following contents. Modify the code to handle the event types that your webhook is subscribed to.
const express = require('express');
const app = express();
app.post('/webhook', express.json({
    type: 'application/json'
}), (request, response) => {
    response.status(202).send('Accepted');
    const data = request.body;
    const datastr = JSON.stringify(data)
    console.log(`handled event: ${datastr}`);
});
const port = 3000;
app.listen(port, () => {
    console.log(`Server is running on port ${port}`);
});

Test the code

To test your webhook, you can use your computer or codespace to act as a local server. If you have trouble with these steps, see Troubleshooting.

  1. Make sure that you are forwarding webhooks. If you are no longer forwarding webhooks, follow the steps in Forward webhooks again.
  2. In a separate terminal window, run the following command to start a local server on your computer or codespace. Replace FILE_PATH with the path to the file where your code from the previous section is stored.
    node FILE_NAME

    You must see output that says Server is running on port 3000.

  3. Trigger your webhook. You can trigger a test webhook by clicking Test Webhook when creating a webhook in your IBM Storage Insights instance.
  4. Navigate to your webhook proxy URL on smee.io. You must see an event that corresponds to the event that you triggered or redelivered. This event indicates that IBM Storage Insights successfully sent a webhook delivery to the payload URL that you specified.
  5. In the terminal window where you ran smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000, you must see something like POST http://127.0.0.1:3000/webhook - 202. This text indicates that smee successfully forwarded your webhook to your local server.
  6. In the terminal window where you ran node FILE_NAME, you must see a message corresponding to the event that was sent.
  7. In both terminal windows, enter Ctrl+C to stop your local server and stop listening for forwarded webhooks.

    Now that you tested out your code locally, you can change your webhook in production. For more information, see Next steps. If you had trouble in testing your code, try the steps in Troubleshooting.

Troubleshooting

If you don't see the expected results that are described in the testing steps, try the following troubleshooting methods:

  • Make sure that your webhook is using your webhook proxy URL (Smee.io URL). For more information about your webhook proxy URL, see Get a webhook proxy URL. For more information about your webhook settings, see Creating a webhook.
  • Make sure that both the smee client and your local server are running. These processes run in two separate terminal windows.
  • Make sure that your server is listening to the same port where smee.io is forwarding webhooks. The example use port 3000.
  • Make sure that the path where smee.io is forwarding webhooks matches a route that is defined in your code. All the examples use the /webhooks path.
  • Check for error messages in the terminal windows where you are running the smee client and your local server.
  • Check IBM Storage Insights to verify that a webhook delivery was triggered.
  • Check your webhook proxy URL on smee.io. You must see an event that corresponds to the event that you triggered or redelivered. This event indicates that IBM Storage Insights successfully sent a webhook delivery to the payload URL that you specified.

Next steps

You now know how to write code to handle webhook deliveries. It also demonstrated how to test your code by using your computer as a local server and by forwarding webhook deliveries from IBM Storage Insights to your local server through smee.io. When you are done testing your code, you might want to modify the code and deploy your code to a server.

Modify the code

The earlier code is a basic example that prints a message when a webhook delivery is received. You can modify the code to take some other action. For example, you can modify the code to perform following actions:
  • Send a message on Slack
  • Open an incident in ServiceNow
  • Update an external project management tool

Payload information

When you test a webhook connection that is created in IBM Storage Insights or an alert is triggered, IBM Storage Insights sends the payload information to your configured application.

Example payload when ransomware threat alert is triggered:
{
  "severity": "critical",
  "deviceType": "flashFamily",
  "subcategory": "SECURITY",
  "creator": "",
  "alert": {
    "source": {
      "deviceModel": "xxx",
      "deviceSerialNumber": "xxxxxxxxxxxxxxxx",
      "deviceType": "FlashSystem xxxx - xxxx",
      "deviceName": "xxxxxxxxxxxx"
    },
    "method": "VOLUME"
  },
  "name": "Ransomware Threat Detection",
  "occurrenceTimeInMs": 1718714498000,
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "resourceType": "Storage System",
  "details": [
    {
      "volumeID": "150",
      "status": "online_threat_detected",
      "hosts": "xxxx-xxxxxx",
      "virtualVolumeID": "",
      "uID": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "description": "The volume has received an anomalous workload. This anomaly could be the result of a new application configuration where encryption is enabled or a security threat such as ransomware"
    }
  ],
  "tenantUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "alertURL": "https://stag.insights.ibm.com/gui/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx#alerts?id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&parentType=storageSystem&parentId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
Example payload when any other alert is triggered:
{
  "severity": "critical",
  "deviceType": "flashFamily",
  "category": "SECURITY",
  "name": "Write-cache Delay Percentage >= 10.0",
  "occurrenceTimeInMs": 1733320427770,
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "tenantUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "deviceName": "tpcflash5200-9"  
  "alertURL": "https://stag.insights.ibm.com/gui/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx#alerts?id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&parentType=storageSystem&parentId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  "Description": "Alert Write-cache Delay Percentage >= 10.0 on ABC was triggered 1 times at Sun 2024- "
}