Send content events to Optimizely Mark 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 agent in Mark (Optimizely Agent Platform) 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 Mark, 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 Mark, with permission to create agents.
- Your CMS (SaaS) instance connected to Mark.
- Administrator access to Settings > Webhooks in CMS (SaaS).
Create the workflow agent in Mark
The workflow agent is the container that holds the trigger and the routing logic.
- Go to Agents > Your Agents in Mark.
- Select Add Agent > Workflow Agent.
- 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.
- Click Save.
Add the webhook trigger in Mark
The webhook trigger provides the agent with a URL that the CMS (SaaS) can call and defines the secret that authenticates the call.
- Drag a Webhook trigger onto the canvas in the workflow editor.
- 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.
- Click Save. Mark updates the remaining settings and generates a webhook URL.
- 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.
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 event data format.
Register the webhook in CMS (SaaS)
Registering the webhook tells CMS (SaaS) which events to send to the Mark trigger URL.
- Go to Settings > Webhooks in CMS (SaaS).
- Click Create Webhook.
- Enter a Name and a Description.
- Paste the webhook URL you copied from Mark in Endpoint URL field.
- Click Add Authentication Token, and enter the same value you used for Auth Key in Mark. The two values must match exactly, or Mark rejects the request.
- Select the category and then select the events you want the agent to receive in the Events section.
- Click Create.
Before CMS (SaaS) saves the webhook, it runs a validation handshake with the Mark URL. If CMS (SaaS) displays a message that the URL could not be validated, confirm that you pasted the complete webhook URL from Mark. See Verify the endpoint.
Build the routing logic in Mark
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.
- Create an External Step Router specialized agent that reads the key value from the payload and returns the CMS (SaaS) content data.
- Add a Condition node that branches on whether the agent retrieved the content data.
- 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 Mark. If the agent does not run, check that the webhook has the Active status in CMS (SaaS), and that the Auth Key in Mark and the Authentication Token in CMS (SaaS) are identical.