Web hooks

⚠ This feature is experimental!

Configuration

The plugin "web-hooks" needs to be installed and loaded for this feature to work.

You can trigger an HTTP POST request to a URL when a Xen Orchestra API method is called.

  • Go to Settings > Plugins > Web hooks
  • Add new hooks
  • For each hook, configure:
    • Method: the XO API method that will trigger the HTTP request when called
    • Type:
      • pre: the request will be sent when the method is called
      • post: the request will be sent after the method action is completed
      • pre/post: both
    • URL: the full URL which the requests will be sent to
  • Save the plugin configuration

From now on, a request will be sent to the corresponding URLs when a configured method is called by an XO client.

Request content

POST / HTTP/1.1
Content-Type: application/json

The request's body is a JSON string representing an object with the following properties:

  • type: "pre" or "post"
  • callId: unique ID for this call to help match a pre-call and a post-call
  • userId: unique internal ID of the user who performed the call
  • userName: login/e-mail address of the user who performed the call
  • method: name of the method that was called (e.g. "vm.start")
  • params: call parameters (object)
  • timestamp: epoch timestamp of the beginning ("pre") or end ("post") of the call in ms
  • duration: duration of the call in ms ("post" hooks only)
  • result: call result on success ("post" hooks only)
  • error: call result on error ("post" hooks only)

Request handling

Quick Node.js example of how you may want to handle the requests

const http = require('http')
const { exec } = require('child_process')

http
  .createServer((req, res) => {
    let body = ''
    req.on('data', chunk => {
      body += chunk
    })
    req.on('end', () => handleHook(body))
    res.end()
  })
  .listen(3000)

const handleHook = data => {
  const { method, params, type, result, error, timestamp } = JSON.parse(data)

  // Log it
  console.log(
    `${new Date(
      timestamp
    ).toISOString()} [${method}|${type}] ${params}${result || error}`
  )

  // Run scripts
  exec(`./hook-scripts/${method}-${type}.sh`)
}

results matching ""

    No results matching ""