IBM Cloud Docs
Configuring webhooks

Configuring webhooks

Webhooks allow IBM Cloud® Internet Services to send real-time notifications to external systems when specific events occur in your account. By integrating webhooks with your alert policies, you can automate responses or trigger workflows in third-party services.

You can configure webhooks using the IBM Cloud console, CLI, or API.

Alerts and webhooks are available only on Enterprise plans.

Configuring webhooks in the console

To configure webhooks in the console, navigate to your Account page and select the Alerts tab. In the Alerts section, select the webhooks tab.

Creating a webhook in the console

  1. Click Create.
  2. Enter a name for your webhook.
  3. Enter the webhook URL. This URL can't be updated; if you want to change it, you must delete and re-create the webhook.
  4. Enter the webhook secret. The secret can't be updated; if you want to change it, you must delete and re-create the webhook.

Editing a webhook in the console

To edit a webhook in the console, click the Edit icon next to the name of the webhook that you want to update. You can edit only the name of the webhook. If you need to modify a webhook, it is recommended that you delete and re-create the webhook instead of editing it.

Deleting a webhook in the console

To delete a webhook in the console, click the Actions menu Actions icon of the webhook that you want to delete, then select Delete. Select Delete in the confirmation window.

Configuring webhooks from the CLI

Creating a webhook from the CLI

To create a webhook from the CLI, run the following command:

ibmcloud cis alert-webhook-create --name NAME --url URL [--secret SECRET] [-i, --instance INSTANCE] [--output FORMAT]

Where:

  • --name value is the name of the webhook.
  • --url value is the POST endpoint to call when an alert is dispatched.
  • --secret value is the secret that is passed in the webhook auth header when a webhook alert is dispatched.
  • -i, --instance value is the instance name or ID. If not set, the context instance that is specified by 'cis instance-set INSTANCE' is used.
  • --output value specifies the output format; only JSON is supported.

Listing all webhooks from the CLI

To list a webhook from the CLI, run the following command.

ibmcloud cis alert-webhooks [-i, --instance INSTANCE] [--output FORMAT]

Where:

  • -i, --instance value is the instance name or ID. If not set, the context instance that is specified by 'cis instance-set INSTANCE' is used.
  • --output value specifies the output format; only JSON is supported.

Getting details for a webhook from the CLI

To get details for a webhook from the CLI, run the following command:

ibmcloud cis alert-webhook WEBHOOK_ID [-i, --instance INSTANCE] [--output FORMAT]

Where:

  • WEBHOOK_ID is the ID of webhook.
  • -i, --instance value is the instance name or ID. If not set, the context instance that is specified by 'cis instance-set INSTANCE' is used.
  • --output value specifies the output format; only JSON is supported.

Updating a webhook from the CLI

To update a webhook from the CLI, run the following command:

ibmcloud cis alert-webhook-update WEBHOOK_ID [--name NAME] [--url URL] [--secret SECRET] [-i, --instance INSTANCE] [--output FORMAT]

Where:

  • WEBHOOK_ID is the ID of webhook.
  • --name value is the name of the webhook.
  • --url value is the POST endpoint to call when an alert is dispatched.
  • --secret value is the secret that is passed in the webhook auth header when a webhook alert is dispatched.
  • -i, --instance value is the instance name or ID. If not set, the context instance that is specified by 'cis instance-set INSTANCE' is used.
  • --output value specifies the output format; only JSON is supported.

Deleting a webhook from the CLI

To delete a webhook from the CLI, run the following command:

ibmcloud cis alert-webhook-delete WEBHOOK_ID [-i, --instance INSTANCE] [-f, --force]

Where:

  • WEBHOOK_ID is the ID of webhook.
  • i, --instance value is the instance name or ID. If not set, the context instance that is specified by 'cis instance-set INSTANCE' is used.
  • -f, --force attempts to delete webhook without prompting for confirmation.

Configuring webhooks with the API

To call these methods, you must be assigned one or more IAM access roles.

  • internet-svcs.zones.read
  • internet-svcs.zones.update

You can check your access by going to Users > name > Access policies.

Creating a webhook with the API

Creating a webhook alert is a two-step process. First, create the webhook, then use the ID in the response that you receive to create the alert.

To create a webhook by with the API, follow these steps:

  1. Set up your API environment with the correct variables.

  2. Store the following variables to be used in the API command:

    • crn: the full URL-encoded CRN of the service instance.
    • name: the name of the webhook.
    • url: the URL of the webhook.
    • secret: the optional secret or API key that is needed to use the webhook.

  3. When all variables are initiated, run the following command to create the webhook:

    curl -X POST
https://api.cis.cloud.ibm.com/v1/:crn/alerting/destinations/webhooks
  -H 'content-type: application/json'
  -H 'x-auth-user-token: Bearer xxxxxx'
  -d '{"name":"Example
Webhook","url":"https://hooks.slack.com/services/Ds3fdBFbV/456464Gdd"}'

The following response is returned:

{
  "result": {
    "id": "6d16fcab-3e80-44b3-b59b-a3716237832e"
  },
  "success": true,
  "errors": [],
  "messages": []
}

Use the ID in the response that you received to create the alert:

curl -X POST \
https://api.cis.cloud.ibm.com/v1/:crn/alerting/policies \
  -H 'content-type: application/json' \
  -H 'x-auth-user-token: Bearer xxxxxx' \
  -d '{"name":"Example Policy","enabled":true,"alert_type":"dos_attack_l7","mechanisms":{"email":[{"id":"cistestemail@ibm.com"}],"webhooks": [{"id": "6d16fcab3e8044b3b59ba3716237832e"}]}}'

Listing all webhooks with the API

To list all webhooks with the API, follow these steps:

  1. Set up your API environment with the correct variables.

  2. Store the following variable to be used in the API command:

    • crn: the full URL-encoded CRN of the service instance.

  3. When all variables are initiated, get the list of webhooks:

    curl -X GET
https://api.cis.cloud.ibm.com/v1/:crn/alerting/destinations/webhooks
  -H 'content-type: application/json'
  -H 'accept: application/json'
  -H 'x-auth-user-token: Bearer xxxxxx'

Getting details for a webhook with the API

To get the details of a webhook with the API, follow these steps:

  1. Set up your API environment with the correct variables.

  2. Store the following variables to be used in the API command:

    • crn: the full URL-encoded CRN of the service instance.
    • webhook_id: alert webhook identifier.

  3. When all variables are initiated, get the webhook details:

    curl -X GET
https://api.cis.cloud.ibm.com/v1/:crn/alerting/destinations/webhooks/:webhook_id
  -H 'content-type: application/json'
  -H 'accept: application/json'
  -H 'x-auth-user-token: Bearer xxxxxx'

Updating a webhook with the API

To update a webhook with the API, follow these steps:

  1. Set up your API environment with the correct variables.

  2. Store the following variables to be used in the API command:

    • crn: the full URL-encoded CRN of the service instance.
    • webhook_id: alert webhook identifier.
    • name: the name of the webhook.
    • url: the URL of the webhook.
    • secret: the optional secret or API key that is needed to use the webhook.

  3. When all variables are initiated, update the webhook:

    curl -X PUT
https://api.cis.cloud.ibm.com/v1/:crn/alerting/destinations/webhooks/:webhook_id
  -H 'content-type: application/json'
  -H 'x-auth-user-token: Bearer xxxxxx'
  -d '{"name":"Example Webhook","url":"https://hooks.slack.com/services/Ds3fdBFbV/456464Gdd"}'

Deleting a webhook with the API

To delete a webhook by with the API, follow these steps:

  1. Set up your API environment with the correct variables.

  2. Store the following variables to be used in the API command:

    • crn: the full URL-encoded CRN of the service instance.
    • webhook_id: alert webhook identifier.

  3. When all variables are initiated, delete the webhook:

    curl -X DELETE
https://api.cis.cloud.ibm.com/v1/:crn/alerting/destinations/webhooks/:webhook_id
  -H 'content-type: application/json'
  -H 'accept: application/json'
  -H 'x-auth-user-token: Bearer xxxxxx'