How do I use webhooks with my hub?

Webhooks are user-defined HTTP callbacks that can use an event on a website or app to trigger a different event on a different website or app. Administrators can create webhooks for your hub that send a POST request to a URL containing JSON for selected authoring events such as creations, updates, and deletions. You can filter these events for specific items types, status, or tags. A webhook can be consumed by a custom HTTP server, or a service like Zapier.  Any response from your webhook consumer is ignored.

Note: Authentication to the Acoustic Content Rest APIs can be included as part of the request sent from Webhooks, a separate login request is not required. For more information, see API explorer.

Only administrators can create and manage webhooks in your hub. They access webhooks from the Webhooks view of the ribbon. To enable this view, an administrator opens the My products view, expands the list of tools for the hub, and enables the Webhooks view.

An administrator might use a webhook to send an email or Slack notification when updates are made to items in the hub. For example, when a composer sets up a review of a content item or asset, a webhook can be used to email any approvers.

An administrator might also use a webhook to send the text of a content item to an external translation system:

  1. Create a webhook that is filtered to send events when Content items are updated with a tag of Ready for translation.
  2. When a content item is ready to be translated, your composer edits the content item and selects Ready for translation. This triggers the webhook you created and sends the text of the content item to your external translation system.
  3. The translated text can be imported into a new content item using the Acoustic Content APIs.

A webhook can be configured to only send events that match specified filters. If no filters are specified, all available events will be sent to the webhook consumer. If the Active option is cleared, no events will be sent to the webhook consumer.

Your webhook consumer should verify that the POST request came from Acoustic Content to prevent malicious attacks on your consumer. Acoustic Content uses the same mechanism as GitHub to allow for this check to happen. A secret can be defined for the webhook, and used as a key to create a hash based on the request body. The hash will be sent as a header called X-IBM-WCH-SIGNATURE. The webhook consumer should run the same hash check using its copy of the secret, and verify that the two hashes match. If not, the request should be rejected. For more information, see https://developer.github.com/webhooks/securing/.

Further samples are available here: https://github.com/ibm-wch/sample-custom-workflows-using-webhooks