Managing content involves several workflows between various channels. For example, you create the content and set up a review. Now the approver might not be a person who is regularly working in the hub. They must be notified of the review request. How would you do that? You cannot expect them to check the hub. You need to notify them through an email or slack.

Here's where Webhooks would become handy. Webhooks are a popular way to communicate between different tools automatically. Acoustic Content provides webhooks to help manage your workflow. Content webhooks send messages when an event occurs in the Content hub.

Here's how Content Webhooks work

1. To get started, you as an administrator would enable Webhooks from the UI and set it up.
2. You would provide the URL of the webhook consumer. The consumer is the application or tool that Acoustic Content communicates with.
3. Once you set up the webhook in Acoustic content, a communication route is created between the two systems.
4. When an event occurs in Acoustic content, a POST request is sent to the URL you provided containing the JSON for the event.
5. This request can in turn trigger another event in the webhook consumer. For example, the consumer you set up could be Zapier and it receives the event notification send an email to the approver.

Setting up and managing Webhooks

Only administrators can create and manage webhooks in your hub. You can create webhooks for selected authoring events such as creations, updates, and deletions. These events can be filtered for the specific event type, item type, status, or tags. When such filters are set webhooks requests are sent only when events that match the specified filters occur. If no filters are specified, then all available events will be sent to the webhook consumer. After a Webhook created it needs to be active to communicate with the consumer. If the Active option is cleared, no events will be sent. Acoustic content does not accept any response from your webhook consumer. Any such response 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.

Managing security

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 Securing your webhooks.

Common use case example

You can use a webhook to send the text of a content item to an external translation system. Here is how you would do it:

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.