---
title: Send content events to Agent Platform with webhooks
slug: cms-saas/docs/send-content-events-to-agent-platform-with-webhooks
docTags: 
createdAt: 2026-09-08T20:17:36.000Z
---

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 Agent Platform 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 Agent Platform, 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](docId\:p3ZC2m-nWzuSy4Q22uKUc).

## Prerequisites

You need the following access before you start:

- Access to Agent Platform, with permission to create agents.
- Your CMS (SaaS) instance connected to Agent Platform.
- Administrator access to **Settings > Webhooks** in CMS (SaaS).

## Create the workflow agent in Agent Platform

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

1. Go to **Agents > Your Agents** in Agent Platform.
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 Agent Platform

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:

:::Paragraph{indent="1"}
**Payload schema**
:::

:::CodeblockTabs{indent="1"}
```json
  {
    "type": "object",
    "properties": {
      "key": {
        "type": "string"
      }
    },
    "required": [
      "key"
    ]
  }
  
```
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Auth Key** – A secure secret that you choose. You enter this same value as the authentication token in CMS (SaaS), so keep it available.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Auth Header Name** – Select **Authorization**.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Auth Header Format** – Select **Bearer \{ token }**.
:::

:::hint{type="info" indent="3"}
**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**. Agent Platform 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.

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](docId\:p3ZC2m-nWzuSy4Q22uKUc).

## Register the webhook in CMS (SaaS)

Registering the webhook tells CMS (SaaS) which events to send to the Agent Platform 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 Agent Platform in **Endpoint URL** field.
5. Click **Add Authentication Token**, and enter the same value you used for **Auth Key** in Agent Platform. The two values must match exactly, or Agent Platform 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 Agent Platform URL. The webhook keeps the **Pending** status until Agent Platform confirms that message, and then changes to **Active**.

## Build the routing logic in Agent Platform

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 Agent Platform. If the agent does not run, check that the webhook has the **Active** status in CMS (SaaS), and that the **Auth Key** in Agent Platform and the **Authentication Token** in CMS (SaaS) are identical.