Webhooks

Webhooks are HTTP-based endpoints that allow you to trigger workflows. They simply send an HTTP post to the webhooks URL, with or without a payload, and a workflow can be triggered. If you choose to include payload data in your request, you must use a valid content-type. The following content-type headers are supported in Automation:

• application/json
• application/json;charset=utf-8
• application/x-www-form-urlencoded
• application/xml

If you send any other type of content, the request will be rejected.

Using RequestBin to Verify Content-Type Header

You can use a website such as RequestBin to check the Content-Type header for any webhooks you want to configure.

1. Open RequestBin. You should see an endpoint URL similar to https://enrszd3sz7aa.x.pipedream.net.
2. Configure the product you want to send webhooks from and then send a webhook to the endpoint URL. After the source product sends a webhook, it will show up in your RequestBin.
3. Select the request in the list on the left to view the request details on the right.
4. Expand the Headers list and look for the Content-Type.
5. When you create the webhook in Automation, select the same Request Content Type as the webhook Content-Type header in RequestBin.
   • If your webhook did not provide a Content-Type header, it is unlikely to work in Automation. Contact support for the source product and see if they can add the header to their webhooks.
   • If the Content-Type header does not match a supported type in Automation, the webhook will not work. Contact Cisco Support to log a request for a new Content-Type header.

When you create a webhook, you will be given an HTTP endpoint where you can push events from the source product. A single webhook can be used to trigger a single workflow or multiple workflows.

1. Choose Automate > Triggers in the navigation menu
2. Click the Webhooks tab and then click New Webhook.
3. In the General section, enter the following information:
   • Display Name - A unique meaningful name for the webhook.
   • Description - Text that describes the webhook, such as what the incoming data will trigger.
   • Request Content Type - Click the drop-down list and choose the Content-Type for your payload (incoming webhook):
     • application/json
     • application/json; charset=utf-8
     • application/x-www-form-urlencoded
     • application/xml
4. Click Submit to create the webhook. The newly created webhook is displayed at the top of the list on the Webhooks tab.
5. In the Display name column on the Webhooks tab, click the webhook to view the generated Webhook ID, AO API Key, and Webhook URL. The URL is where the source product of the webhook will push events.

You can now go to the Automation Rules tab and create a Webhook rule to listen for incoming data from the webhook. This rule will be used as a trigger to execute the associated workflow.

To trigger a webhook, you can either configure a source product to send events to the Webhook URL or you can POST your own events using standard HTTP requests. Authentication is provided by the API key in the URL, and the request must have both Content Type and Accept headers. A request body is not required, but allows you to pass data to your workflow.

• North America: https://automate.us.security.cisco.com

• Europe: https://automate.eu.security.cisco.com

• Asia Pacific, Japan, and China: https://automate.apjc.security.cisco.com

Example Requests

• POST to trigger a webhook with no request body:

  POST /webhooks/01MYFX09T0JZeDFNggAd92MlpAaWgoi?api_key=+61NtR8LBuYNMtBw6bdqwPAe8oGoIzjZuFxIXt/C8/MMfKE2R6d6WDppBLWWwYdywgMqInyClmAP7qN1ePi0H6vBFgHQIa5xnaT4P9iY++02X064s1+Q== HTTP/1.1
  Host: automate.us.security.cisco.com
  Content-Type: application/json
  Accept: application/json              

• POST to trigger a webhook with a JSON payload:

  POST /webhooks/01MYFX09T0JZeDFNggAd92MlpAaWgoi?api_key=+61NtR8LBuYNMtBw6bdqwPAe8oGoIzjZuFxIXt/C8/MMfKE2R6d6WDppBLWWwYdywgMqInyClmAP7qN1ePi0H6vBFgHQIa5xnaT4P9iY++02X064s1+Q== HTTP/1.1
  Host: automate.us.security.cisco.com
  Content-Type: application/json
  Accept: application/json
  Content-Length: 85
  {
      "key": "value",
      "list_of_stuff": [
          "item1",
          "item2"
      ]
  }               

If your request was accepted by Automation, you will receive a 202 Accepted HTTP response with no body.

If your webhook responds with an HTTP status code other than 202, validate the following:

• The webhook is tied to an event.
• The webhook URL is correct, including the api_key.
• The HTTP request type is a POST.
• The Accept header is set to application/json.
• The Content-Type header is set to one of the values supported by Automation. If your webhook responds with a 415 error, this indicates an incorrect or missing header.
• If your webhook responds with an HTTP status code of 429, you may be sending too many webhooks and hitting a rate limit. External events are limited to 5,000 executions per day across all event types and up to 5 executions per minute individually.

If your webhook responds with a 202, but your workflow does not run, check the following:

• The webhook is tied to an event and the event is configured correctly as a trigger in your workflow.
• The workflow is in a valid state (the validation button should say Validated in the Workflow Editor).

Note: Webhooks created before the January 20, 2022 release require new API keys. To resolve this, edit and save the webhook and make note of the new API key. Then update any source systems with the new API key.