16 Use Webhooks

Oracle Content Management provides incoming webhooks you can use to receive event notifications from external applications.

You can also use outgoing webhooks to automatically push notifications of content publishing, content lifecycle, site publishing, and prerendering events to other applications.

Outgoing Webhooks

You can use outgoing webhook endpoints for push notifications of content publishing, content lifecycle, site publishing, and prerendering events.

Configure Outgoing Webhooks

You can use outgoing webhooks to have Oracle Content Management automatically post notifications based on asset and site events.

For example, you might want to post a notification to an application when new content is published, so that the application can consume the new content.

To create an outgoing webhook:

  1. After you sign in to the Oracle Content Management web application as an administrator, click Integrations in the Administration area of the navigation menu on the left.
  2. In the Integrations menu, click Webhooks.
  3. Click Create.
  4. Select the type of webhook you want to create:
    • Asset Lifecycle Webhook: Receive push notifications about asset lifecycle changes in a repository.
    • Asset Publishing Webhook: Receive push notifications about assets published to a channel or unpublished from a channel.
    • Site Publishing Webhook: Receive push notifications about site publishing.
    • Prerender Webhook: Receive push notifications about the need to render and cache a site detail page.
  5. Enter a name and description for the webhook. This name appears as a heading for the posted conversation message.
  6. Enable the webhook.
  7. Provide information for webhook monitoring:
    • If you're creating an asset lifecycle webhook, select the repository you want to monitor for asset events.
    • If you're creating a site publishing webhook, specify the name of the site you want to monitor for site events.
    • If you're creating a prerender webhook, notify Prerender about the need to render and cache a Detail page.
  8. Select the events you want to generate notifications.
  9. Select whether you want brief or detailed information about each event. For a site publishing webhook, you can also select an empty notification.
    • For asset lifecycle webhooks, brief notifications include who triggered event, what was the event, what item was involved with the event, in which repository the event occurred, and when the event occurred. Detailed notifications include the same information listed in brief plus a list of all the fields in each content item or digital asset.
    • For asset publishing webhooks, brief notifications include the ID of each published asset. Detailed notifications include the same information listed in brief notitfications plus a list of all the fields in each published asset.
  10. Enter the target URL (endpoint) to which you want to post notifications.
  11. If the endpoint requires authentication, select what type of authentication, and then click Details to enter the authentication information.

    Oracle Content Management webhooks support the following options to configure authentication for the webhook notification receiver:

    • None: The receiver does not require authentication.
    • Basic: The receiver requires Basic Auth.
    • Header: The receiver requires a Secure Header.
  12. Click Save.

To delete a webhook, click Delete next to the webhook.

To edit a webhook, click Edit next to the webhook.

Monitor Webhook Events

As an administrator or developer, you can access a log of events posted to a Webhook. The Events Log displays the Object IDs, Event IDs, and Published dates and times for webhook activities in an Oracle Content Management instance.

To monitor Webhook events:

  1. After you sign in to the Oracle Content Management web application as an administrator or developer, click Integrations in the Administration area of the navigation menu on the left.
  2. In the Integrations menu, click Webhooks admin UI.
  3. On the Settings view for a webhook instance, choose the option to open the Events log page.

    The Events log page displays a list of all the events published to this webhook. Recent posts are shown at the top.


Description of webhook-log.jpg follows
Description of the illustration webhook-log.jpg

For each event, the log also shows its response status (Success or Failure). You can expand a posted event to see details about notifications sent to a webhooks client.

The Oracle Cloud REST API for Activity Log provides the ability to search activities in Oracle Content Management. This API has the following endpoints:
  • Audit Log, which provides the details of activities and related data.
  • Events, which provides the details of types and categories.

Use Endpoints for Push Notifications of Content Lifecycle, Content Publishing, Site Publishing, and Prerendering Events

Oracle Content Management automatically delivers notifications to webhook endpoints about content publishing, content lifecycle, site publishing, and prerendering events.

You subscribe to events for your webhooks to receive notification when the events happen, in the payloads for the endpoints. For example, if your endpoint subscribes to an event called DIGITALASSET_CREATED, when a digital asset is created in a repository you specified, the webhook payload can tell you the name of the webhook, what time the event happened, and who did the event.

You can use an endpoint to be notified when some action happens. Then Oracle Content Management calls that endpoint. You can create webhooks using REST endpoints, similar to other REST APIs. You need to specify a server URL for each webhook endpoint. The GET, POST, PUT, and DELETE endpoints are hosted on the Oracle Content Management server, so the same host name, port, and system is the context for all the webhook endpoints.

You can create all the content items with the REST API headless endpoints. You can also create webhooks using the REST API, and listen to the events.

The webhook endpoints are as follows:

GET /webhooks          Lists all webhooks.
POST /webhooks         Creates a webhook with the given information in the payload.
GET /webhooks/{id}     Reads a webhook with the given ID.
PUT /webhooks/{id}     Updates a webhook with the given information in the payload.
DELETE /webhooks/{id}  Deletes a webhook with the given ID.

Or you can create, configure, enable, or disable webhooks in the Oracle Content Management web UI at Administration > Integrations > Webhooks > Settings. See Configure Webhooks.

You can view event payloads, with Brief or Detailed output. Webhook payloads contain the following data:

  • Which webhook got invoked
  • What event got triggered (maybe CONTENTITEM_UPDATED or CHANNEL_ASSETPUBLISHED)
  • When the event was registered, and which user triggered it
  • What entity is the subject of the event:
    • For content lifecycle webhooks, it can be a content item or digital asset.
    • For content publishing events, it will be a list of the identifiers of all published content.

Webhooks have three different formats, as the following table describes.

Format Output
Brief Output includes only basic information in the payload. The output gives you details like what the action is, when it happened, in what repository, and who did the action.
Detailed Output includes all content information in the payload. The output gives you the whole content item data, in a URL that you specify.
Empty Available only for content publishing webhooks. If you specify Empty for the output, the payload contains only an identifier representing the publish session ID.

If the endpoint requires authentication, you can select what type of authentication and then enter the authentication information.

Receive Push Notifications from a Prerender Webhook

A prerender webhook can send you push notifications for prerender events in Oracle Content Management.

A site manager can create a new prerender webhook with a REST API endpoint or on the Administration > Integrations > Webhooks > Settings page in the Oracle Content Management web interface.

This outgoing webhook for the prerenderer enables you to set up anotification about a aprerender event, which enhances the prerender server to allow prerendering and caching of a Detail page after an asset is published to the site's channel.

As an administrator, you can create a Site Detail Page Refresh Webhook to notify Prerender about the need to render and cache a Detail page.

Receive Push Notifications from a Content Lifecycle Webhook

A content lifecycle webhook can send you push notifications about content lifecycle events in an Oracle Content Management repository for content items and taxonomies.

You can receive information about the following events from a content lifecycle webhook:

  • Content Item Created
  • Content Item Updated
  • Content Item Deleted
  • Content Item Approved
  • Content Item Published
  • Content Item Republished
  • Content Item Unpublished
  • Digital Asset Created
  • Digital Asset Updated
  • Digital Asset Deleted
  • Digital Asset Approved
  • Digital Asset Published
  • Digital Asset Republished
  • Digital Asset Unpublished
  • Collection Created
  • Collection Deleted

A respository manager can create a content lifecycle webhook with a REST API endpoint or on the Administration > Integrations > Webhooks > Settings page in the Oracle Content Management web interface. On the Settings page for a webhook, users can configure the following settings:

  • Name: A webhook name
  • Description: A webhook description
  • Status: An enabled or disabled status for the webhook. The default is disabled
  • Repository: A repository to scope events for the webhook
  • Events: A list of events for the webhook to send notifications
  • Target URL: The URL of the endpoint to which notifications should be posted
  • Authentication: A callback receiver security (None, Basic, or Header)
  • Payload: The type of payload to send to the endpoint. (Brief or Detailed)

Name, Description, Status, Target URL, and Authentication are standard settings for a webhook. For the repository setting, pick a repository for which you have Manager permission.

Receive Push Notifications from a Content Publishing Webhook

A content publishing webhook can send you push notifications for asset and taxonomy publishing events in Oracle Content Management.

You can receive information about the following events from a content publishing webhook:

  • Asset Published to Channel
  • Asset Republished to Channel
  • Asset Unpublished to Channel
  • Taxonomy Published
  • Taxonomy Republished
  • Taxonomy Unpublished
A channel manager can create a new content publishing webhook with a REST API endpoint or on the Administration > Integrations > Webhooks > Settings page in the Oracle Content Management web interface. This enables notifications about content published to the following channels:
  • Public or secure custom publishing channels
  • Publishing channels that Oracle Content Management creates for public or secure enterprise sites
You can receive notifications about the following activities in the scope of a channel:
  • Publish: A new content item, digital asset, or taxonomy is published.
  • Republish A new version of a content item, digital asset, or taxonomy is published.
  • Unpublish: A content item, digital asset, or taxonomy is unpublished.

Receive Push Notifications from a Site Publishing Webhook

A site publishing webhook can send you push notifications for site publishing events in Oracle Content Management.

A site manager can create a new site publishing webhook with a REST API endpoint or on the Administration > Integrations > Webhooks > Settings page in the Oracle Content Management web interface. This enables notifications about site publish, republish, and unpublish events.

Receive Push Notifications from a Prerender Webhook

A prerender webhook can send you push notifications for prerender events in Oracle Content Management.

A site manager can create a new prerender webhook with a REST API endpoint or on the Administration > Integrations > Webhooks > Settings page in the Oracle Content Management web interface.

This outgoing webhook for the prerenderer enables you to set up anotification about a aprerender event, which enhances the prerender server to allow prerendering and caching of a Detail page after an asset is published to the site's channel.

As an administrator, you can create a Site Detail Page Refresh Webhook to notify Prerender about the need to render and cache a Detail page.

Incoming Webhooks

You can use webhooks to have Oracle Content Management automatically receive a notification based on various events happening in the external services.

The incoming webhooks framework provides a way with which external applications or services can call and notify Oracle Content Management about various events that are required by Oracle Content Management. The webhook framework provides a means for validating the incoming request with token-based authentication.

  1. After you sign in to the Oracle Content Management web application as an administrator or developer, click Integrations in the Administration area of the navigation menu on the left.
  2. The Oracle Content Management components that need webhook support will create an incoming webhook instance. For example, when you create a Lingotek translation connector, as Request a Lingotek Trial Connector for Content Translation describes, the connector framework in the background creates an instance of the incoming webhook that gets associated with that connector. In the Integrations menu, click Webhooks to see the list of webhook instances of Lingotek translation connectors.
  3. On creating a webhook instance, the framework generates a security token with a configurable duration of validity. Every incoming request should have this token. The framework validates the incoming request by verifying the token and its expiry.

    The component submits a callback URL and token to the external application. When any event in which the component has subscribed to the external application occurs, the component makes a call back to Oracle Content Management over the same URL.

    Click the check box next to your incoming webhook instance, and then select Edit from the action toolbar. Or, you can click on the clickable name of the incoming webhook to get to the Edit page. On the General page, you can specify the values for Service Valid For and Security. Name and Description are populated at the time the incoming webhook is created, but you can change these values if you want to.The Target URL field is read-only. The server generates the URL when the webhook instance is created.

    After clicking the checkbox you'll need to select Edit from the action toolbar. Or, you can click on the clickable name of the incoming webhook to get to the Edit page.
  4. The Event Log page displays a list of all the events. The list displays the login ID, date and time when the event occurred, status (success or failure), and download icon (to download the event log).

Configure an Incoming Webhook

Use the Oracle Content Management web interface to configure adapter fields and the CAL adapter for an incoming Webhook.

To configure a Lingotek Incoming Webhook:

  1. After you sign in to the Oracle Content Management web application as an administrator, click Integrations in the Administration area of the navigation menu on the left.
  2. In the Integrations menu, click Webhooks.
  3. Fill in the following fields for the Lingotek-Incoming Webhook.

    The Name and Description fields are populated at the time the Incoming Webhook is created. You can edit and change these values if you want to.


Description of lingotek-incoming-webhook.png follows
Description of the illustration lingotek-incoming-webhook.png

Use the CAL-Based Webhook Adapter

The CAL-based webhook adapter publishes the details of an incoming request on the CAL network.

Any interested component can consume the event and further process it. A component that needs to consume the webhook can implement the processor.