Outbound webhooks
3 minute read
An outbound webhook is an action of the Webhook type. It integrates CMP with external systems that expose a web-based API, typically REST. Use one to post a message to a channel whenever a particular blueprint is deployed, create an entry in a CMDB when a new server is built, or enable and disable monitoring when a user selects a button on the server details page.
To let an external system call CMP instead, see Inbound webhooks.
Webhook fields
In addition to the fields common to all actions, such as name and description, a webhook has the following:
| Field | Description |
|---|---|
| URL | The address CMP sends the request to. |
| HTTP Method | The verb to use: DELETE, GET, HEAD, PATCH, POST, or PUT. |
| Authentication Method | No authentication, HTTP basic auth, or Token-based. Basic auth also needs a username and password. Token-based auth also needs an auth header name and value; check the external API’s documentation for the header it expects, for example an Authorization header with a value of Bearer <your API token>. |
| Content Type | The content type of the payload: JSON, WWW-Form, or XML. |
| Payload | The data to send in the request body. |
| Custom headers | A JSON object whose keys are HTTP header names and whose values are header values, for example {'user-agent': 'my-app/0.0.1'}. Some headers cannot be overridden; see the Requests documentation on custom headers. |
Webhook parameterization
When you create or edit a webhook, CMP parses the URL, Payload, and Custom headers fields for template variables such as {{ variable }}, and creates an action input for each one it finds. See Action input parameters for more on automatically generated inputs, and Action context for the objects available to a webhook in each context.
How a webhook runs
CMP makes the HTTP request to the specified URL. A response code between 200 and 299 counts as success; anything else is a failure. The response code is shown in the job progress.
Restrict which URLs a webhook can reach
The External URL Whitelist setting controls which external addresses webhooks may contact. It also governs actions whose source code is fetched from an external URL. The default is .*, which allows everything.
- Go to Admin > Miscellaneous Settings.
- Open the Resource management tab and select Edit.
- Find External URL Whitelist and enter a semicolon-separated list of allowed domains. Entries support regular expressions and IPv4 addresses, for example
.*\.internal\.loc; 192\.168\..*; my\.domain\.com. - Select Save.
Webhooks compared with plugins
Anything a webhook can do can also be done by a plugin. The webhook type exists to remove the need to write code for straightforward integrations, which makes them quicker to create and maintain. Reach for a plugin instead when you need logic around the call, such as contacting the API only under certain conditions or processing the response in a particular way. A plugin can use the Python requests library to make the same HTTP call.