How to trigger workflow agents with Content Marketing Platform webhooks
Webhooks let Optimizely Content Marketing Platform (CMP) notify Optimizely Opal automatically when something changes in CMP, such as tasktask, campaigncampaign, assetasset, or work requestwork request. For example, CMP can send a webhook when a task starts, when a task moves to a new workflow step, or when a work request is created.
This guide walks through connecting a CMP webhook to an Opal workflow agent. The example uses the external_sub_step_started event, but you can apply the same pattern to any CMP webhook eventCMP webhook event.
The following steps describe the end-to-end flow:
- A user advances a CMP task to an external workflow step.
- CMP sends a webhook to Opal with the task context.
- The Opal workflow agent receives the webhook and routes it to the correct specialized agent.
- That agent performs the work. For example, updating the task brief.
- Another agent completes the CMP workflow step, advancing the task automatically.
The following diagram shows the end-to-end flow from a CMP task advancing to an external step through Opal completing the automation.
Use this pattern as the foundation for AI-powered content automation with Opal. Apply it to content generation, compliance checks, and approval workflows.
Prerequisites
Ensure you have the following before starting:
- Opal administrator or Agent Builder role in Opal.
- Administrator access in CMP to create webhookswebhooks and CMP workflowsCMP workflows.
- Access to the CMP instance you want to connect.
- Opal connected to your CMP instance (with Opal connections).
Architecture
How external steps work
CMP workflowsCMP workflows move taskstasks through internal steps handled by team members. External steps defer processing to systems outside CMP, in this case, an Opal workflow agent.
When a task reaches an external step, the following occurs:
- CMP fires a webhook with the event external_sub_step_started.
- The webhook payload includes the task_id, step_id, sub_step_id, and the external system name.
- The Opal workflow agent receives this payload and uses the external system name to route to the correct processing logic.
- When processing is complete, Opal calls back to CMP to mark the step as done.
Key components
Component | Platform | Purpose |
|---|---|---|
Webhook | CMP | Sends notification when external step starts. |
External system | CMP | Labels and identifies the type of external work. |
Workflow agent | Opal | Orchestrates the multi-step automation. |
External step router agent | Opal | Routes webhook to correct processing branch. |
Specialized agents | Opal | Perform the actual work and complete the step. |
Create the Opal webhook trigger
Before configuring CMP, create the Opal workflow agent and webhook trigger to generate the webhook URL you need for the CMP configuration.
Create a workflow agent
Follow these steps in Opal:
- Go to Agents > Your Agents.
- Click Add Agent > Workflow Agent.
- Enter CMP External Step Handler for the Name.
- Enter cmp_external_handler for the Id.
- Enter Handles CMP external workflow steps by routing to appropriate agents and completing steps. for the Description.
- Click Apply.
- Click Save.
Add the webhook trigger
Follow these steps in Opal:
- Drag and drop a Webhook trigger into the editor.
- Enter CMP External Step Webhook for the Name.
- Enter Receives webhooks when CMP external step starts. for the Description.
- Select the CMP product instance you connected in the prerequisites from the Product Instance drop-down list.
- Keep application/json selected for the Payload Content Type drop-down list.
- Enter a secure secret for the Auth Key. Enter this same value as the Secret when creating the CMP webhook in the next section.
- Select Custom for the Auth Header Name drop-down list.
- Enter Callback-Secret in the Enter custom header name field.
- Enter for the Auth Header Format.
- Click Save.
Click Copy to clipboard for the generated Webhook URL.
The URL displays in the following format: https://webhook.opal.optimizely.com/webhooks/UUID/UUID.
Click Save on the Opal workflow agent. Keep this browser tab open. Return to it after completing the CMP configuration.
CMP configuration
Create the webhook
Register a webhook in CMP that notifies the Opal workflow agent when external steps start. CMP supports many webhook events. This guide uses external_sub_step_started as an example. Find all available events on the webhook registration page in CMP or see the list of webhooks in the CMP developer documentation.
- Go to Settings (your profile picture) > Apps & Webhooks.
- Go to the Webhooks tab.
- Click Register New > General Webhook.
- Enter Opal External Step Automation for the Name.
- Enter Triggers Opal workflow agent when external steps start. for the Description.
- Paste the webhook URL you copied from Opal into the Callback URL field.
- Enter the same secret you entered as the Auth Key in Opal for the Secret. This value must match exactly.
- Select the external_sub_step_started checkbox. Select additional events on this page as needed.
- Click Create Webhook.
Note
The Auth Key in Opal must exactly match the Secret you entered when creating the webhook in CMP. If the values do not match, the webhook is rejected.
Create a CMP workflow with an external step
Create a CMP workflow template that includes an external step.
Create the CMP workflow
- Open a new browser tab and go to CMP.
- Go to Settings > Workflows.
- Click Add Workflow (or edit an existing one).
- Enter AI-Assisted Content Workflow for the Workflow Title.
- Go to the Steps tab.
- Click Add Step to create your workflow structure.
Add a step and convert to external
- Enter AI Brief Enhancement for the Title for your step.
- Expand the step to see configuration options.
- Click More (...) > Convert to External Step.
Configure the external system
The external system name is what the Opal workflow agent uses to route the webhook to the correct processing logic. This value must match the value referenced in the External Step Router agent prompt.
- Click Manage external systems.
- Click Add External System.
- Enter AI_Brief_Enhancement for the External System.
- Click Save.
- Select AI_Brief_Enhancement from the Select external system drop-down list.
- Click Save to save the entire CMP workflow.
Webhook payload reference
When the external step starts, CMP sends a webhook payload like the following:
{
"data": {
"task_id": "abc123-task-guid",
"step_id": "step-guid",
"sub_step_id": "sub-step-guid",
"status": "started",
"external_system": "AI_Brief_Enhancement"
},
"event": "external_sub_step_started",
"timestamp": "2026-01-31T10:30:00Z"
}The external_system value is what the External Step Router agent in Opal uses to determine which processing branch to run.
Build the Opal workflow agent
Return to Opal to create the specialized agents and assemble the full workflow.
Create the External Step Router agent
The External Step Router specialized agent extracts the external system name from the webhook payload and outputs a routing value. The routing value is a string you define. It is what you reference in the following Condition node to decide which agent runs next.
For example, if the external system is AI_Brief_Enhancement, you can output BRIEF_UPDATE and then add a condition that checks for BRIEF_UPDATE to route to the Task Brief Updater agent.
To create the External Step Router specialized agent using JSON import, see Import a specialized agent from JSON and paste the following JSON:
{
"schema_version": "1.0",
"agent_type": "specialized",
"name": "External Step Router",
"output": {
"type": "text",
"schema": null,
"description": null
},
"version": "1.0.0",
"agent_id": "external_step_router",
"file_urls": [],
"is_active": true,
"creativity": 0.1,
"is_deleted": false,
"parameters": [
{
"name": "external_system",
"type": "string",
"default": null,
"required": true,
"description": "The external system name from the CMP webhook payload "
}
],
"description": "Routes external step web hooks to the correct processing agent based on external system name.",
"prompt_pills": null,
"enabled_tools": null,
"agent_metadata": null,
"inference_type": "rudimentary",
"initial_message": null,
"prompt_template": "You are a router agent. Your only job is to output a routing value based on the external system name provided.\\nThe external system is: [[external_system]]\\nOutput ONLY the routing value according to this logic:\\n\\\\- If external_system equals \\"AI_Brief_Enhancement\\" → output \\"BRIEF_UPDATE\\"\\n\\\\- If external_system does not match any known value → output \\"UNKNOWN\\"\\nProvide only the routing value with no additional text or explanation.",
"internal_version": 1,
"conversation_mode": false,
"first_prompt_mode": "open",
"is_enabled_in_chat": true,
"memory_token_limit": 8000,
"evaluation_criteria": null,
"system_prompt_template": ""
}Alternatively, follow these steps in Opal to create it manually:
- Go to Agents > Your Agents.
- Click Add Agent > Specialized Agent.
- Enter External Step Router for the Name.
- Enter external_step_router for the Id.
- Enter Routes external step webhooks to the correct processing agent based on external system name. for the Description.
- Enter the following for the Prompt Template. Update the routing logic to match the external system names you configured in CMP and the output values you want to use in your Condition nodes. The external system name must exactly match the value you entered in the CMP external system setup.
You are a router agent. Your only job is to output a routing value based on the external system name provided.
The external system is: [[external_system]]
Output ONLY the routing value according to this logic:
- If external_system equals "AI_Brief_Enhancement" → output "BRIEF_UPDATE"
- If external_system does not match any known value → output "UNKNOWN"
Provide only the routing value with no additional text or explanation.- Click Add variable.
- Select String for the Type.
- Enter external_system for the Name.
- Enter The external system name from the CMP webhook payload. for the Description.
- Select the Required? checkbox.
- Click Save Variable.
- Select Quick for the Inference Level.
- Click Save.
Create the Task Brief Updater agent
The Task Brief Updater specialized agent updates the task brief with AI-generated content. To create the Task Brief Updater agent using JSON import, paste the following:
{
"schema_version": "1.0",
"agent_type": "specialized",
"name": "Task Brief Updater",
"output": {
"type": "text",
"schema": null,
"description": null
},
"version": "1.0.0",
"agent_id": "task_brief_updater",
"file_urls": [],
"is_active": true,
"creativity": 0.5,
"is_deleted": false,
"parameters": [
{
"name": "task_id_or_url",
"type": "string",
"default": null,
"required": false,
"description": "The task ID from the task."
}
],
"description": "Updates a CMP task brief with AI-generated content.",
"prompt_pills": null,
"enabled_tools": [
"get_cmp_resource",
"update_task_brief"
],
"agent_metadata": null,
"inference_type": "simple_with_thinking",
"initial_message": null,
"prompt_template": "\\\\## Role\\n\\nYou are a Task Brief Enhancement agent. Your job is to read an existing task brief and enhance it with additional context.\\n\\n\\\\## Process\\n\\n1\\\\. Use `get_cmp_resource` with resource_type \\"task\\" and the provided [[task_id_or_url]] to retrieve the current task details and brief.\\n\\n2\\\\. Review the existing brief content.\\n\\n3\\\\. Use `update_task_brief` to append a confirmation message to the brief:\\n\\n Add the following at the end of the existing brief content:\\n\\n ---\\n\\n \\n\\n \\\\## AI Processing Complete\\n\\n \\n\\n ✅ This task was processed by the External Step Workflow automation.\\n\\n \\n\\n **Processed at:** [current timestamp]\\n\\n **Status:** Enhancement complete\\n\\n \\n\\n ---\\n\\n4\\\\. Preserve ALL existing brief content—only append the new section.\\n\\n\\\\## Output\\n\\nConfirm that the brief was updated successfully and provide the task URL.",
"internal_version": 1,
"conversation_mode": false,
"first_prompt_mode": "open",
"is_enabled_in_chat": true,
"memory_token_limit": 8000,
"evaluation_criteria": null,
"system_prompt_template": ""
}Alternatively, follow these steps in Opal to create it manually:
- Go to Agents > Your Agents in Opal.
- Click Add Agent > Specialized Agent.
- Enter Task Brief Updater for the Name.
- Enter task_brief_updater for the Id.
- Enter Updates a CMP task brief with AI-generated content. for the Description.
- Enter the following in the Prompt Template:
## Role
You are a Task Brief Enhancement agent. Your job is to read an existing task brief and enhance it with additional context.
## Process
1. Use `get_cmp_resource` with resource_type "task" and the provided [[task_id_or_url]] to retrieve the current task details and brief.
2. Review the existing brief content.
3. Use `update_task_brief` to append a confirmation message to the brief:
Add the following at the end of the existing brief content:
---
## AI Processing Complete
✅ This task was processed by the External Step Workflow automation.
**Processed at:** [current timestamp]
**Status:** Enhancement complete
---
4. Preserve ALL existing brief content — only append the new section.
## Output
Confirm that the brief was updated and provide the task URL.- Click Add Variable.
- Select String for the Type.
- Enter task_id_or_url for the Name.
- Enter The task ID from the task. for the Description.
- Select the Required? checkbox.
- Click Save Variable.
- Click Add tool.
- Search for and select the following tools:
- get_cmp_resource
- update_task_brief
- Click Add selected.
- Select Balanced for the Inference Level.
- Click Save.
Create the Workflow Step Completer agent
The Workflow Step Completer specialized agent marks the CMP workflow step as complete. To create the Workflow Step Completer agent using JSON import, paste the following:
{
"schema_version": "1.0",
"agent_type": "specialized",
"name": "Workflow Step Completer",
"output": {
"type": "text",
"schema": null,
"description": null
},
"version": "1.0.0",
"agent_id": "workflow_step_completer",
"file_urls": [],
"is_active": true,
"creativity": 0.1,
"is_deleted": false,
"parameters": [
{
"name": "task_id_or_url",
"type": "string",
"default": null,
"required": false,
"description": "The task ID containing the step to complete."
}
],
"description": "Completes an external workflow step in CMP",
"enabled_tools": [
"update_task_substep"
],
"agent_metadata": null,
"inference_type": "rudimentary",
"prompt_template": "You are a Workflow Step Completer agent. Your job is to mark the current workflow step as complete in CMP.\\n\\n\\\\## Process\\n\\n1\\\\. Use `update_task_substep` with the provided [[task_id_or_url]] the **step_name** is \\"AI Brief Enhancement\\".\\n\\n2\\\\. Set the action to \\"complete\\".\\n\\n3\\\\. This will advance the task to the next workflow step.\\n\\n\\\\## Output\\n\\nConfirm that the step was completed successfully.",
"internal_version": 1,
"is_enabled_in_chat": true
}Alternatively, follow these steps in Opal to create it manually:
- Go to Agents > Your Agents.
- Click Add Agent > Specialized Agent.
- Enter Workflow Step Completer for the Name.
- Enter workflow_step_completer for the Id.
- Enter Completes an external workflow step in CMP. for the Description.
- Enter the following for the Prompt Template:
## Role
You are a Workflow Step Completer agent. Your job is to mark the current workflow step as complete in CMP.
## Process
1. Use `update_task_substep` with the provided [[task_id_or_url]].
2. Set the action to "complete".
3. This advances the task to the next CMP workflow step.
## Output
Confirm that the step was completed.- Click Add Variable.
- Select String for the Type.
- Enter task_id_or_url for the Name.
- Enter The task ID containing the step to complete. for the Description.
- Select the Required? checkbox.
- Click Save Variable.
- Click Add tool.
- Search for and select the update_task_substep tool.
- Click Add selected.
- Select Standard for the Inference Level.
- Click Save.
Assemble the workflow agent
Connect all the specialized agents in your Opal workflow agent.
Access your workflow agent
Follow these steps in Opal:
- Go to Agents > Your Agents.
- Click the CMP External Step Handler agent you created in the Create a workflow agent section.
Add your first agent
- Drag and drop the External Step Router agent into the editor below the CMP External Step Handler webhook.
- Connect the CMP External Step Handler webhook and External Step Router agent. To do so, click the CMP External Step Handler's connector circle.
Drag the connector to the External Step Router agent.
Add a condition
The Condition node reads the output value from the External Step Router agent and directs the workflow to the correct next agent. The value you enter in Matching Condition must match the routing value output by the router, for this example, BRIEF_UPDATE.
- Drag and drop a Condition into the editor adjacent to the External Step Router agent.
- Click the Condition to edit it.
- Click Add Condition.
- Select Equals for the Match Type.
- Enter BRIEF_UPDATE for the Matching Condition.
- Connect the External Step Router agent to the Condition. To do so, click the External Step Router's connector circle and drag the connector to the Condition.
Add the remaining agents
- Drag and drop the Task Brief Updater agent into the editor in the Drag and drop step area.
- Drag and drop the Workflow Step Completer agent into the editor below the Task Brief Updater agent.
- Connect the Task Brief Updater agent and Workflow Step Completer agent. To do so, click the Task Brief Updater's connector circle and drag the connector to the Workflow Step Completer agent.
- Click Save.
Test your workflow
Run the test
Follow these steps in CMP:
- Click Create New > Task.
- Enter AI-Assisted Content Workflow for the Title.
- Select AI-Assisted Content Workflow you created in the Create a CMP workflow with an external step section for the Workflow.
- Enter a Due Date.
- (Optional) Enter additional information to the task.
- Click Create.
Advance the task to the AI Brief Enhancement external step. To do so, click on the step and select In progress or advance through the previous steps.
Verify the results
Confirm the workflow ran end to end by checking both Opal and CMP.
Follow these steps in Opal to review the workflow logs:
- Go to Agents > Workflow Logs.
- Click the latest execution of the CMP External Step Handler Opal workflow agent.
- Select each individual workflow agent and verify everything ran correctly.
- Verify the Workflow Execution is Completed.
Follow these steps in CMP to review the task brief updates:
- Go to Plan.
- Click your AI-Assisted Content Workflow task.
- Verify the task brief was updated by the Opal workflow agent and the AI Brief Enhancement step is marked complete.
The following are points to check and their expected results:
- Webhook received – Execution displays in Opal history.
- Router output – Displays the routing value you defined in the router prompt.
- Brief updated – Task brief contains the appended AI processing message.
- Step completed – CMP shows the external step as complete.
- Task advanced – Task is on the next CMP workflow step or the CMP workflow is complete.
Troubleshoot
Webhook does not trigger
Check the following if the webhook does not trigger:
- Callback URL incorrect – Verify you copied the URL exactly from Opal.
- Event not selected – Confirm you selected external_sub_step_started.
- Workflow agent not active – Toggle the Opal workflow agent to active.
Router does not match
Check the following if the router does not return the expected value:
- External system name typo – Verify the exact spelling in CMP matches the router logic.
- Case sensitivity – External system names are case-sensitive.
- Missing condition – Add a condition for your external system in the router prompt.
Step does not complete
Check the following if the CMP workflow step does not advance:
- Tool not enabled – Ensure you added the update_task_substep tool to the specialized agent.
- Task ID not passed – Verify the task_id_or_url variable is flowing through the Opal workflow agent.
- Permission error – Check that Opal is connected to the correct CMP instance. See Product connections.
Next steps
When you have the basic workflow running, expand your Opal workflow agent by implementing the following:
- Add more external systems – Expand your router to handle different CMP workflow step types.
- Build specialized agents – Create agents for content generation, compliance checks, and translations.
- Update the Condition for additional options – Add conditions for other external_system values, such as COMPLIANCE_CHECK and UNKNOWN.
- Implement error handling – Add conditional branches for failure scenarios.
- Configure notifications – Use the send_email tool to notify users of completion.
Note
If you use Opti ID, administrators can turn off generative AI in the Opti ID Admin Center. See Turn generative AI off across Optimizely applicationsTurn generative AI off across Optimizely applications.