Use Webhooks

18 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 asset publishing, asset lifecycle, site publishing, prerendering, and scheduled jobs events to other applications.

The following topics describe how to use webhooks:

Outgoing Webhooks

You can use outgoing webhook endpoints for push notifications of asset publishing, asset lifecycle, site publishing, prerendering, and scheduled jobs 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:

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.
In the Integrations menu, click Webhooks.
Click Create.
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 Page Refresh Webhook: Receive push notifications about the need to render and cache a site detail page.
- Scheduled Jobs Webhook: Receive push notifications about publishing jobs scheduled in a repository.
Enter a name and description for the webhook. This name appears as a heading for the posted conversation message.
Enable the webhook.
Provide information for webhook monitoring:
- If you're creating an asset lifecycle webhook, select the repository you want to monitor for asset events. You can filter the notifications by Asset Types, which applies only to events published for content items or digital assets of chosen types.
- If you're creating an asset publishing webhook, select the publishing channels you want to monitor for asset publishing 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.
- If you're creating a scheduled jobs webhook, select the repository you want to monitor for scheduled jobs events.
Select the events you want to generate notifications.
Select whether you want brief or detailed information about each event.
- 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 notifications plus a list of all the fields in each published asset.
Enter the target URL (endpoint) to which you want to post notifications.
If the endpoint requires authentication, select the type of authentication, and click Details to enter the authentication information.
Oracle Content Management (OCM) 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.
To allow endpoints to use Self-Signed SSL certificates, which is recommended only in testing or development, select the corresponding checkbox:
- Self-signed SSL certificate: The receiver accepts a self-signed SSL certificate.
To authenticate the call between your service and Oracle Content Management when event notifications are sent to your webhook endpoints, OCM signs the event with a signature. The signature is a security token in hash-based message authentication (HMAC) code, using the standard SHA-256 HMAC cryptography. You can use the HMAC token to verify that the notifications are sent by Oracle Content Management.
Enable the signature-based security option on the configuration page for outgoing webhooks by selecting the corresponding checkbox. Enter a secret key consisting of alphanumeric characters (lowercase letters a-z, digits 0-9) and is 32 characters.
- Signature-based security: The receiver requires the server and client authentication tokens to be equal.
When an event of interest is triggered, a webhook payload is sent to your application with the X-OCM-Webhook-Signature header in the signed event. The X-OCM-Webhook-Signature header includes an epoch timestamp and a signature, for example:
```
{
            X-OCM-Webhook-Signature: 
            t=1660807672,
            v=d1b1ea85b53f8dd435a96f59d778d9cdb09be1905d1cecc7acdf4e03ecf60a1b
}
```
The value of t is an epoch timestamp, computed at the time of sending the request and is used in computing the signature v when sending the request.

The value of v is a signature, computed from t and the payload, i.e.hash(t + ”.” + payload)
Upon receiving the webhook request, verify the signature:
1. Obtain the values of the epoch timestamp t and the signature v by parsing the request headerX-OCM-Webhook-Signature.
2. Compute the current epoch timestamp t1 and ensure that the difference between t1 and t (epoch timestamp obtained from step a) is not more than the threshold, such as 30 or 60 seconds. Go to the next steps only if the difference between the epoch timestamps is less than the threshold.
3. Use the value of timestamp t from step a and the payload from the request to create a string by concatenating as follows:
  t + “.” + payload
4. Using the secret key from the webhook configuration page when you opted for the signature-based security, compute the HMAC signature of the string created in step c with SHA-256 algorithm. Ensure that the signature is encoded in hex before proceeding to the next step. The javax.crypto.Mac (part of jdk-1.8 library) can be used to generate the HMAC signature. Additionally, a third-party library such as Bouncy Castle can also be used to generate the signature for the payload.
5. Compare the signature generated in step d with the signature from the request header. Continue with further processing of the request only if the signature values match.
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:

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.
Click Webhooks in the Integrations dropdown menu.
On the settings page 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 the illustration webhook-log.png

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 following table shows the details of the events that are triggered:

Event	Details
`SCHEDULEDPUBLISHING_PARENTCREATED` - create a recurring scheduled publishing job	Key: cec.event.scheduledpublishing.parentcreated.name Display Name: Scheduled publishing job created Message Detail: Scheduled publishing recurring job '{job-name}' '{job-id}' created at '{datetime}'
`SCHEDULEDPUBLISHING_PARENTUPDATED` - properties of the whole recurring job is updated (for example, the series name or description is updated, job manager is added or removed)	Key: cec.event.scheduledpublishing.parentupdated.name Display Name: Scheduled publishing job updated Message Detail: Scheduled publishing recurring job '{job-name}' '{job-id}' updated at '{datetime}'
`SCHEDULEDPUBLISHING_CREATED` - create a scheduled publishing job	Key: cec.event.scheduledpublishing.created.name Display Name: Scheduled publishing job created Message Detail: Scheduled publishing job '{job-name}' '{job-id}' with assets '{the-first-10-asset-guids}' created at '{datetime}'
`SCHEDULEDPUBLISHING_UPDATED` - update a scheduled publishing job	Key: cec.event.scheduledpublishing.updated.name Display Name: Scheduled publishing job updated Message Detail: Scheduled publishing job '{job-name}' '{job-id}' with assets '{the-first-10-asset-guids}' updated at '{datetime}'
`SCHEDULEDPUBLISHING_CANCELLED` - cancel a scheduled publishing job	Key: cec.event.scheduledpublishing.cancelled.name Display Name: Scheduled publishing job cancelled Message Detail: Scheduled publishing job '{job-name}' '{job-id}' with assets '{the-first-10-asset-guids}' cancelled at '{datetime}'
`SCHEDULEDPUBLISHING_STARTED` - scheduled publishing job is started	Key: cec.event.scheduledpublishing.started.name Display Name: Scheduled publishing job started Message Detail: Scheduled publishing job '{job-name}' '{job-id}' with assets '{the-first-10-asset-guids}' started at '{datetime}'
`SCHEDULEDPUBLISHING_COMPLETED` - scheduled publishing job is completed	Key: cec.event.scheduledpublishing.completed.name Display Name: Scheduled publishing job completed Message Detail: Scheduled publishing job '{job-name}' '{job-id}' with assets '{the-first-10-asset-guids}' completed at '{datetime}' A failed reason will be appended if the job is failed. Message Detail: Scheduled publishing job '{job-name}' '{job-id}' with assets '{the-first-10-asset-guids}' completed at '{datetime}'. {if-failed-failed-reason}

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

Oracle Content Management automatically delivers notifications to webhook endpoints about asset publishing, asset lifecycle, site publishing, prerendering, and scheduled jobs 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. 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 asset lifecycle webhooks, it can be a content item or digital asset.
- For asset 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 asset 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 an Asset Lifecycle Webhook

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

You can receive information notifications about the following events for your webhooks:

Events that are available for webhook type asset lifecycle

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

Name: A webhook name.
Description: A webhook description.
Type: A webhook type.
Enable Webhook: An enabled or disabled status for the webhook. The default is disabled.
Repository: A repository for setting the event scope for the webhook notifications.
Asset Types: A list of asset types for setting the event scope of the webhook notifications. The filtering feature applies only to events published for content items or digital assets of chosen types.
- Use the All asset types option to receive notifications about lifecycle events for assets of any type that is assigned or will be assigned to the repository(s).
- Use the Select individual asset types option to receive notifications about lifecycle events for assets of chosen types only. As an administrator, you can select both content and digital asset types. Note that only asset types that are assigned to the selected repository(s) are displayed in the asset type picker.
Events: A list of events for the webhook to receive notifications. Use the All current and future events option for the webhook to receive notifications for all events. Use the Select individual events option for the webhook to receive notifications for specific events.
Payload: The type of payload to send to the endpoint. (Brief or Detailed)
Target URL: The URL of the endpoint to which notifications should be posted.
Authentication: A callback receiver security (None, Basic, Header)
Self-signed SSL certificate: The receiver accepts a self-signed SSL certificate.
Signature-based security: The receiver requires the server and client authentication tokens to be equal.

Name, Description, Enable Webhook, 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 an Asset Publishing Webhook

An asset 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 an asset publishing webhook:

Events notifications supported by asset publishing webhook

A channel manager can create a new asset 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 assets 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:

Published: A new content item, digital asset, or taxonomy is published.
Unpublished: 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 for site events with types including published, status, and unpublished.

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 a notification about a prerender 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 Scheduled Jobs Webhook

A scheduled jobs webhook can send you push notifications for publishing jobs scheduled in a repository in Oracle Content Management.

A site manager can create a new scheduled jobs webhook with a REST API endpoint or on the Administration > Integrations > Webhooks settings page in the Oracle Content Management web interface. This enables notifications for scheduled publishing jobs in a repository.

You can receive notifications for scheduled job events with types including created, updated, canceled, started, and completed.

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.

Note:

Incoming webhooks aren't supported in private instances.

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.
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.
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 checkbox 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.
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:

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.
In the Integrations menu, click Webhooks.
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.