In your deployment.yml file add the hooks entry and provide a list of action configurations.

Each Hook has two required keys plus optional configuration depending on the type of Hook and Event. The required keys are:

• type: what Hook behaviour to run

• event: which Event to subscribe

The two optional keys are:

• with - configuration parameters for the action

• filter - options to limit when an Event is triggered

If there are multiple Hooks for the same Event, they are not guaranteed to run in any order.

The http Hook allows you to make any kind of HTTP Request. The url key is requried and all others are optional.

• url - the request URL

• method - the request method (default POST)

• body - the request Body Content (see below)

• timeout - the request Timeout in ms (default 5000, 5 seconds)

• bearer_token - Bearer Authentication Token (without Bearer prefix)

• custom_headers - dictionary of additional HTTP Header values

• url_is_template - pass url through Template::Toolkit (default true)

• body_is_template - pass body content through Template::Toolkit (default true)

• ignore_failure - treat non-2xx responses or timeout as OK (default false)

The url and body keys are templates that allow inserting data provided by the Event within matching [% …​ %], as in the examples given. The set of accessible substitutions depends on the Event (e.g. a Device database row).

The body key can either contain a plain string or some YAML. If a string, then it’s passed directly as the request’s Body Content. If YAML then Netdisco will convert to JSON and pass that as the Body Content (as a string) - this is probably easier for you than giving a JSON String template.

If no body is specified in an action configuration then all the available metadata from the Event are included as a JSON String.

For HTTP Basic Authentication, provide the username and password inline within the url. The default Content Type is application/json; use the custom_headers setting to override this.

The exec Hook allows users to run an arbitrary shell command when triggered.

The command is executed on a separate child process in synchronous fashion. This means the Netdisco worker will wait for the command to finish, so beware of long running processes tieing up your workers.

A non-zero exit status will resut in a "failed" Hook job in your job queue. The STDOUT and STDERR are recorded and stored, along with the exit status, in a JSON data structure in the job’s subaction field.

The cmd key is required, and others are optional:

• cmd - command to run

• cmd_is_template - pass cmd through Template::Toolkit (default true)

• timeout - timeout, in seconds, for the command execution (default 60)

• ignore_failure - treat non-zero responses as OK (default false)

For various reasons (described in the perlfunc exec man page) it’s safer to pass a list to cmd with the program and each of its arguments. This is not required, though, and a single string also works (see examples below).

The shell command is executed with the following additional environment:

This Event occurs after Netdisco successfully discovers any device. More precisely, at the end of the Discover job, a new job is queued with high priority to run the Hook immediately.

This Event functions identically to the discover Event, except that it only fires on the successful first discovery of a new device. Note that the discover event will still also fire for newly discovered devices.

This Event occurs after Netdisco deletes any device, either on user action in the web or at the CLI, or through the Expiry job. After the device is deleted, a new job is queued with high priority to run the Hook immediately.

This Event occurs after Netdisco successfully gathers MAC address table data from any device. More precisely, at the end of the Macsuck job, a new job is queued with high priority to run the Hook immediately.

This Event occurs after Netdisco successfully gathers ARP (MAC to IP mapping) data from any device. More precisely, at the end of the Arpnip job, a new job is queued with high priority to run the Hook immediately.