> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.cxplanner.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 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
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 to start immediately, or disable it to save paused.
6. Click **Save**.
7. 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](https://storage.crisp.chat/users/helpdesk/website/-/e/a/2/c/ea2cfd7bb6130800/image_zy3ryv.png)

### Edit a webhook
1. Go to **Settings** - **Webhooks**.
2. Locate the webhook in **Outbound webhooks**.
3. Click **Details**.
4. Update the endpoint URL, event types, or active status.
5. 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](https://storage.crisp.chat/users/helpdesk/website/-/e/a/2/c/ea2cfd7bb6130800/image_2n5d8j.png)

### Delete a webhook
1. Locate the webhook in **Outbound webhooks**.
2. Click **Delete**.
3. Type **delete** in the confirmation field.
4. 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
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.

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