Articles on: Integrations & Advanced Features

Configuring outbound webhooks for a project

Overview: outbound webhooks

The Webhooks feature in Project Settings sends signed HTTPS POST notifications to your endpoint when selected project events occur, which is used to connect CxPlanner to automation platforms, ticketing systems, monitoring tools, or custom backends.

Your role must be project Admin.
You can find the menu at Project Settings - Webhooks.
This changes external deliveries, audit logs, and delivery history for the project.

Only users with the project role Admin can manage webhooks, and the company must have the ProjectWebhooks Enterprise plugin enabled.

Available event types: Task assigned, Task created, Task updated, Checklist user group assigned, Checklist signed.

How to configure outbound webhooks

Create a webhook

Open the project and go to Settings.
Select Webhooks.
Enter your Endpoint URL.
Select the Event types you want to receive.
Leave Active enabled to start immediately, or disable it to save paused.
Click Save.
Copy the signing secret when you see Copy this signing secret now. You will not see it again.

The signing secret is only displayed once. Store it securely before leaving the page.

Screenshot: Create outbound webhook form with endpoint and event types

Edit a webhook

Go to Settings - Webhooks.
Locate the webhook in Outbound webhooks.
Click Details.
Update the endpoint URL, event types, or active status.
Click Save.

The signing secret is not shown again while editing. To get a new secret, delete the webhook and create a new one.

Screenshot: Edit outbound webhook details

Delete a webhook

Locate the webhook in Outbound webhooks.
Click Delete.
Type delete in the confirmation field.
Click Delete to confirm.

Deletion is permanent. Delivery history for the webhook is also removed.

Results: outbound webhooks

Action	Who can perform it
Enable the ProjectWebhooks plugin for a company	CxPlanner backend administrator
Create, edit, or delete webhooks	Project role Admin
Send test deliveries	Project role Admin
View delivery history	Project role Admin

If the Webhooks tab is missing or shows that webhooks are not enabled for your company, contact your CxPlanner administrator or CxPlanner Support to enable the Enterprise feature.

Endpoint URL requirements

Requirement	Description
HTTPS	Endpoints must use HTTPS. HTTP is not supported.
Blocked domains	Domains belonging to cxplanner.com are not allowed.
Public access	Endpoints must be publicly reachable from the internet.

HTTP headers included in every delivery

Header	Value
Content-Type	application/json
X-CxPlanner-Signature	sha256=HMAC-SHA256 of the body
X-CxPlanner-Event	Event type, for example task.assigned
X-CxPlanner-Delivery	Unique delivery UUID

Payload structure

All webhook events use the same JSON envelope. The data object holds event-specific fields.

{
  "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

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

Always calculate the signature using the raw request body. Parsing and re-serializing JSON can change formatting and fail verification.

Retry policy

Attempt	Delay before next attempt
1	Initial delivery
2	About 5 seconds
3	About 30 seconds
4	About 2 minutes
5	About 10 minutes
6	About 30 minutes
7	About 2 hours
8	About 6 hours
9	About 12 hours

Automatic disablement and history retention

If an endpoint fails 5 consecutive deliveries, CxPlanner disables the webhook and records it in the project audit log. After you fix the endpoint, a project Admin can open Details, check Active, and click Save.

Type	Retention
Visible deliveries in UI	Up to 50 recent deliveries per webhook
Successful deliveries	30 days
Failed deliveries	90 days

Troubleshooting: outbound webhooks

Problem	Cause	Solution
Webhooks tab says the feature is not enabled	ProjectWebhooks Enterprise plugin not enabled	Ask your CxPlanner administrator or CxPlanner Support to enable ProjectWebhooks for the company
Cannot see the Webhooks tab	Project role is below Admin	Ask a project Admin to raise your role or manage webhooks for you
Lost the signing secret	Secret is shown only once at creation	Delete the webhook, create a new one, copy the new secret, and update your endpoint
Endpoint receives repeated deliveries	Endpoint is not returning a 2xx HTTP response	Fix the endpoint to return 2xx, then confirm with Send test
Webhook was automatically disabled	Endpoint failed 5 consecutive deliveries	Fix the endpoint, then re-enable Active in Details and save
Signature verification fails	HMAC calculated on parsed JSON, or wrong secret	Compute HMAC on the raw body with the current signing secret
Send test shows a delivery but endpoint got nothing	Endpoint not publicly reachable over HTTPS	Confirm public HTTPS access and check the delivery status in history
Deliveries marked as failed	Endpoint unreachable or returning errors	Fix the endpoint, wait for the next retry, or use Send test
Need to retry a previous delivery	Manual retries are not supported	Use Send test to create a new test delivery

Updated on: 07/26/2026

Was this article helpful?

Thank you!