Configuring outbound webhooks for a project

Overview

How do I configure webhooks so external systems automatically receive notifications from CxPlanner?

The Webhooks feature in the Project Settings module allows you to send automated HTTP POST notifications to external HTTPS endpoints when selected project events occur. This feature is used to integrate CxPlanner with automation platforms, ticketing systems, monitoring tools, or custom backend applications.

This guide covers creating, editing, testing, disabling, deleting, and monitoring project webhooks. It does not cover implementation of the receiving endpoint beyond basic signature verification. || Only users with the project role Admin can manage webhooks, and the company must have the ProjectWebhooks Enterprise plugin enabled.

When and why to use this

Use webhooks when project activity in CxPlanner should trigger actions in external systems.

• Use webhooks to notify external systems when tasks or checklists change.
• CxPlanner sends a signed HTTP POST request to your registered endpoint.
• You can subscribe to specific event types.
• Endpoints must support HTTPS.
• Webhooks can be paused without being deleted.
• CxPlanner automatically disables webhooks after repeated delivery failures.
• The signing secret is only shown once during creation.

Available event types:

• Task assigned
• Task created
• Task updated
• Checklist user group assigned
• Checklist signed

How to - step by step

Create a webhook

1. Open the project and go to Settings.
2. Select Webhooks.
3. Enter your Endpoint URL.
4. Select the Event types you want to receive.
5. Leave Active enabled if the webhook should start immediately.
6. Disable Active if you want to save it in a paused state.
7. Click Save.
8. Copy the signing secret when the message "Copy this signing secret now. You will not see it again." appears.

Edit a webhook

1. Navigate to Settings → Webhooks.
2. Locate the webhook in the Outbound webhooks list.
3. Click Details.
4. Update the endpoint URL, event types, or active status.
5. Click Save.

The signing secret is not displayed again during editing. If you need a new secret, delete the webhook and create a new one.

Delete a webhook

1. Locate the webhook in the Outbound webhooks list.
2. Click Delete.
3. Type delete in the confirmation field.
4. Click Delete to confirm.

Behavior and results

Permission matrix

If the Webhooks tab is unavailable or displays "Webhooks are not enabled for your company. Please contact support to enable this enterprise feature.", contact your CxPlanner administrator or CxPlanner Support.

Endpoint URL requirements

HTTP headers included in every delivery

Payload structure

All webhook events use the same JSON envelope. The data object contains event-specific information.

{
  "event": "task.assigned",
  "schemaVersion": 1,
  "projectId": "123",
  "entityUuid": "uuid-of-the-entity",
  "actorUuid": "uuid-of-the-user-who-triggered-the-event",
  "timestamp": "2026-05-30T09:00:00Z",
  "data": {}
}

Signature verification

When a webhook is created, CxPlanner generates a signing secret. This secret is used to verify that incoming webhook deliveries originate from CxPlanner.

1. Read the raw request body before parsing it.
2. Compute HMAC-SHA256(raw_body, signing_secret).
3. Compare the result as sha256=<hmac> against the X-CxPlanner-Signature header.
4. Reject the request if the signatures do not match.

Retry policy

If your endpoint does not return a 2xx HTTP status code, CxPlanner retries delivery using exponential backoff.

Automatic webhook disablement

If an endpoint fails 5 consecutive deliveries, CxPlanner automatically disables the webhook and records the event in the project audit log.

Once the endpoint issue has been resolved, a project administrator can re-enable the webhook by opening Details, checking Active, and clicking Save.

Delivery history retention

Troubleshooting

Quick facts

• Requires: Project role Admin and the ProjectWebhooks Enterprise plugin
• Location: Project Settings → Webhooks
• Affects: External integrations, webhook deliveries, audit logs, and delivery history
• Endpoint requirement: HTTPS
• Delivery type: Signed HTTP POST requests
• Automatic disablement: After 5 consecutive delivery failures
• History retention: 30 days for successful deliveries, 90 days for failed deliveries

Updated on: 06/02/2026