Set up webhooks and workflow

Set up the two outbound connections CM Box makes to your systems: webhooks that POST to a URL when content changes, and a workflow connection that drives package approvals through an external workflow engine. This page covers the admin UI setup; for delivery payloads, event semantics, and the engine handshake protocol, see Webhooks and workflow integration.

Before you start: webhook administration requires the admin.webhooks.* permissions and workflow administration the admin.workflows.* permissions (see Security). Have the receiving URL ready.

Create a webhook

1. In the admin area, open Webhooks.
2. Click Add Webhook. In the Add New Webhook dialog, enter a Name (required), the URL to POST to, pick the Repository the webhook listens to, and optionally a description. Click Add.
3. The new webhook appears as a card in the list — filter by repository or search by name to find it. New webhooks are created disabled, so nothing fires until you finish configuring it.
4. Click the card to open the editor and configure:
   • URL — the delivery endpoint. The Repository field is read-only after creation.
   • Subscribed Events — click Add Event and pick one or more of: ITEM_CREATED, ITEM_UPDATED, ITEM_DELETED, ITEM_PUBLISHED, ITEM_ARCHIVED, ITEM_UNARCHIVED, ITEM_CATEGORIZED, ITEM_DECATEGORIZED, FOLDER_CREATED, FOLDER_UPDATED, FOLDER_DELETED, SITE_PUBLISHED, PACKAGE_MERGED.
   • Types Filter — click Add Type to limit the webhook to specific content types; leave it empty to match all types.
   • Payload Size — Full, Basic, None, or Custom. See payload sizes for what each body contains.
   • Custom Payload Template — shown only for Custom: a JSON template for the entire request body, with {{event}}, {{data.*}}, and {{webhook.*}} placeholders and a Format JSON button. The template is required and must be valid JSON.
   • Request Headers — click + Add Header to send extra headers. Check Static Value to send the value as-is; leave it unchecked to resolve the value as a dot-notation path against the item data.
   • Payload Mapping — shown for non-Custom sizes: + Add Payload Mapping copies values from the item data to extra top-level keys in the body, with the same Static Value choice.
   • Include Extracted Text in Payload — check to keep the item’s extracted full text in deliveries (it is stripped by default).
5. Switch Enabled on and click Save.

Verify a webhook

Perform a matching action in the repository (for example, update an item of a subscribed type) and confirm your endpoint receives the POST. Deliveries run on the background queue, so also check the Webhooks queue on the queue dashboard for failed jobs — see Queues. Each delivery is attempted once; CM Box does not retry failures.

Connect a workflow engine

A workflow connection points CM Box at your engine; each connection holds one or more workflow definitions that name a flow the engine can run. The handshake the engine must implement is documented in Webhooks and workflow integration.

1. In the admin area, open Workflows.
2. Click Add Connection. In the Add New Workflow Connection dialog, enter:
   • Name — a label for the engine.
   • Base URL — the engine’s API root, for example https://workflow-engine.example.com/api.
   • Callback Base URL — the CM Box URL the engine calls back to, for example https://cmbox.example.com.
   • Auth Type — how CM Box authenticates to the engine: None, Bearer Token, Basic Auth, or API Key.
3. Click Add, then open the new connection card to finish. The fields the editor shows depend on the auth type: a Bearer Token, a Username and Password, or an API Key plus a Header Name (defaults to X-API-Key).
4. Under Workflow Definitions, click + Add Definition and enter a Name, an optional Description, the Process Definition Key your engine uses for this flow (for example content-approval-v1), and the Initial Trigger URL — the engine path, relative to the base URL, that CM Box posts to when starting the flow (for example /webhook/start).
5. Click Save.

Enable workflow on a repository

Workflow runs on update packages, so the repository must have the Packaged Updates feature enabled before its workflow settings appear.

1. Open the repository’s settings (see Repositories) and expand Workflow Settings.
2. Switch Enable Workflow on.
3. Choose a Default Workflow and select the Available Workflows authors may pick from — both lists offer the definitions you created above.
4. Optionally switch on Auto-merge packages when workflow completes, and then Auto-publish items (and site, if present) after auto-merge if approved content should go live without a manual step.
5. Optionally define Auto-Package Rules to route matching content into packages (and workflow approval) automatically: each rule names the content types and categories it matches, a package strategy (rolling or individual), an optional workflow override, whether it triggers on Create or Update, and whether it is Strict — blocking direct saves to the main repository. Users holding the content.skip_workflow permission can bypass strict rules.
6. Click Save Config.

Verify the connection

Start a workflow on a test package in that repository. CM Box posts the start call to the engine at the definition’s trigger URL; the package’s workflow state then shows the engine’s steps and status. If the start fails, re-check the Base URL, the auth settings, and that the engine can reach the Callback Base URL.

Troubleshooting

• Webhook never fires — confirm the Enabled toggle is on (new webhooks start disabled), the event is in Subscribed Events, and the Types Filter is empty or includes the item’s type. The webhook only listens to the repository chosen at creation.
• Custom payload arrives as the full payload — the custom template is missing or invalid JSON; delivery falls back to the full body. Use Format JSON in the editor to validate the template.