Webhooks documentation for the dotCMS Content Management System

dotCMS supports firing custom webhooks at every point of a content lifecycle using custom Workflow Actions which can include custom Workflow Sub-Actions implemented via Java classes or Velocity scripts. Since every 3rd party system has different hooks which require different parameters, methods and HTTP headers, the ability to script when and how dotCMS fires webhooks is a very powerful and flexible tool.

The Velocity Scripting Workflow Sub-Action

When the “Velocity Script” Workflow Sub-Action is added to a Workflow Action, the Velocity script is executed whenever that Workflow Action is executed for a piece of content. This Sub-Action provides access to all the Velocity tooling built into dotCMS, including the ability to call or post the values of that content to remote REST endpoints using the $json Viewtool.

Examples

There are a number of tools online which can help developers and integrators test webhooks. For the sake of these examples, we are using a tool called PostBin, which simply accepts any incoming webhook and reports back on the request. The examples below require that you get a PostBin id with which to test.

Example 1: Fire a Webhook when Content is Published

  1. Navigate to the Workflows Tool (Types & Tags -> Workflows) in the dotCMS back-end.
  2. Select the Workflow Scheme you wish to add the webhook to.
    • In this example, we will use the System Workflow.
  3. Click the “Save / Publish” Workflow Action to edit the Action.
  4. In the list of Sub-actions, add a new Sub-action “Velocity Script”
  5. Click on the “Velocity Script” Sub-action, to open its properties.
  6. Set the “Script Code” property to the following:
    $json.fetch("https://postb.in/[YOUR_POSTBIN_ID]?action=PUBLISH&identifier=$content.identifier")
    
  7. Save the Workflow Action.
  8. In the Content Search screen, edit a piece of content.
  9. Execute the “Save / Publish” Action for that content.
  10. Open PostBin and navigate to the reporting page.
Result:

You should see that:

  • The webhook has fired for your content, and
  • The content identifier has been passed in appropiately.

Example 2: POST Content Values with a Custom Header to a Webhook

  1. Navigate to the Workflows Tool (Types & Tags -> Workflows) in the dotCMS back-end.
  2. Select the Workflow Scheme you wish to add the webhook to.
    • In this example, we will use the System Workflow.
  3. Click the “Save / Publish” Workflow Action to edit the Action.
  4. In the list of Sub-actions, add a new Sub-action “Velocity Script”
  5. Click on the “Velocity Script” Sub-action, to open its properties.
  6. Set the “Script Code” property to the following:
    #set($headers = {})
    #set($params = {})
    $headers.put("secretKey", "abc-123")
    $params.put("userName", "$user.fullName")
    $params.put("workflowAction", $workflow.action.name)
    $params.put("workflowNextStep", $workflow.nextStep.name)
    #foreach($entry in $contentlet.map.entrySet())
        $params.put($entry.getKey(), "$entry.getValue()")
    #end
    $json.put("https://postb.in/[YOUR_POSTBIN_ID]", $headers, $params)
    
  7. Save the Workflow Action.
  8. In the Content Search screen, edit a piece of content.
  9. Execute the “Save / Publish” Action for that content.
  10. Open PostBin and navigate to the reporting page.

Adding the script in a workflow to fire a webhook

Result:

You should see that:

  • The webhook has fired for your content, and
  • The content's values have been passed in appropiately, including:
    • The custom header,
    • The name of the User who fired the workflow, and
    • The Workflow Action that was executed.

Webhook result