Send content events to Opal with webhooks

Content changes create follow-up work, such as translating a published page, reviewing it before launch, or telling another system about it. A webhook lets an Optimizely Opal agent respond to content changes in CMS (SaaS) automatically. When a content manager publishes, moves, or deletes content, the agent picks the change up and runs the work that follows, such as translation, review, or an update to another system. No one has to start that work by hand.

The integration has four stages. You create a workflow agent in Opal, give it a webhook trigger, register that trigger URL as a webhook in CMS (SaaS), and then add the logic that acts on the event. Both products share one secret, which the webhook trigger and the CMS (SaaS) webhook must set to the same value.

For the full set of webhook fields and event types, see Use webhooks to automate the content lifecycle.

Prerequisites

You need the following access before you start:

• Access to Opal, with permission to create agents.
• Your CMS (SaaS) instance connected to Opal.
• Administrator access to Settings > Webhooks in CMS (SaaS).

Create the workflow agent in Opal

The workflow agent is the container that holds the trigger and the routing logic.

1. Go to Agents > Your Agents in Opal.
2. Select Add Agent > Workflow Agent.
3. Complete the following fields:
   • Name – Identifies the agent, for example CMS Create Content Workflow.
   • Id – The identifier other steps use to reference the agent, for instance cmp_external_handler.
   • Description – Explains what the agent does, for example Listens for content created in CMS to route downstream actions.
4. Click Save.

Add the webhook trigger in Opal

The webhook trigger provides the agent with a URL that the CMS (SaaS) can call and defines the secret that authenticates the call.

1. Drag a Webhook trigger onto the canvas in the workflow editor.

2. Complete the following fields:

   • Name – Identifies the trigger, for example, CMS Create Content Webhook.
   • Description – Explains what the trigger does, for example Receives webhooks when CMS adds content.
   • Product Instance – Your connected CMS (SaaS) instance.
   • Payload Content Type – Select application/json.
   • Payload Schema – (Optional) Define this to validate the shape of the payload before the agent runs. If you define a payload schema, use the schema for the event you subscribe to. The schema for a content event is:
   Payload schema

   {
     "type": "object",
     "properties": {
       "key": {
         "type": "string"
       }
     },
     "required": [
       "key"
     ]
   }

   • Auth Key – A secure secret that you choose. You enter this same value as the authentication token in CMS (SaaS), so keep it available.
   • Auth Header Name – Select Authorization.
   • Auth Header Format – Select Bearer {token}.

     📘

Note

CMS (SaaS) always sends the token in an Authorization header, formatted as Bearer followed by the token, so the header name and format must match these values.

3. Click Save. Opal updates the remaining settings and generates a webhook URL.
4. Click Copy to clipboard for the generated webhook URL. The URL has the format https://webhook.opal.optimizely.com/webhooks/UUID/UUID.

Keep this browser tab open, because you will return to it to build the routing logic.

📘

Note

The payload schema varies by event type. In CMS (SaaS), use View data format on the webhook to copy the schema for the event you subscribe to. Keeping that page open while you configure the trigger makes it easier to compare the two. See View the data format.

Register the webhook in CMS (SaaS)

Registering the webhook tells CMS (SaaS) which events to send to the Opal trigger URL.

1. Go to Settings > Webhooks in CMS (SaaS).
2. Click Create Webhook.
3. Enter a Name and a Description.
4. Paste the webhook URL you copied from Opal in Endpoint URL field.
5. Click Add Authentication Token, and enter the same value you used for Auth Key in Opal. The two values must match exactly, or Opal rejects the request.
6. Select the category and then select the events you want the agent to receive in the Events section.
7. Click Create.

CMS (SaaS) sends a verification message to the Opal URL. The webhook keeps the Pending status until Opal confirms that message, and then changes to Active.

Build the routing logic in Opal

The trigger only delivers the event. The content payload identifies the content item by its key, so the workflow retrieves the content data before it acts on the event.

1. Create an External Step Router specialized agent that reads the key value from the payload and returns the CMS (SaaS) content data.
2. Add a Condition node that branches on whether the agent retrieved the content data.
3. Connect the specialized agent that performs the work to the successful branch.

Verify the integration

Perform an action in CMS (SaaS) that matches one of the events you subscribed to, such as creating content, and then confirm that the agent runs in Opal. If the agent does not run, check that the webhook has the Active status in CMS (SaaS), and that the Auth Key in Opal and the Authentication Token in CMS (SaaS) are identical.