Custom Webhook

elean can send task events as signed JSON payloads to any HTTP endpoint you control — new tasks, assignments, status and priority changes, comments, updates, and deletions.

Setup

Open Integrations

Go to Workspace Settings → Integrations and find the Custom Webhook card.

Configure the endpoint

Click Connect and enter the Endpoint URL that should receive POST requests. elean generates a Signing Secret for you — use it to verify incoming requests.

Optional settings

Set Max retry attempts (1–10, default 5) and any custom headers to include on every request.

Choose events

Select which events should be sent to that endpoint. You can change this at any time.

Payload

Each request is a POST with a JSON body:

{
  "event": "task.created",
  "data": { "...": "event-specific fields" },
  "timestamp": "2026-07-15T12:00:00.000Z"
}

For example, a task.status_changed event:

{
  "event": "task.status_changed",
  "data": {
    "event": "task.status_changed",
    "taskId": "8f3c2a1e-5b7d-4c9a-9e2f-1a6b3d4c5e7f",
    "taskExternalId": "ENG-42",
    "taskTitle": "Fix login redirect on mobile",
    "projectId": "2d9e4f1a-7c3b-4a8e-b6d5-9f0e1c2a3b4d",
    "workspaceId": "6a1b2c3d-4e5f-4a7b-8c9d-0e1f2a3b4c5d",
    "workspaceSlug": "acme",
    "actorId": "c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
    "actorName": "Jane Doe",
    "oldStatus": "In Progress",
    "newStatus": "Done"
  },
  "timestamp": "2026-10-06T09:30:00.000Z"
}

oldStatus and newStatus are the status names as shown in the project. actorId is null when the change came from the Public API or the system. Payloads can include additional fields; rely only on the ones documented here. Requests include these headers:

Header	Description
`X-Elean-Signature`	HMAC SHA-256 of the raw request body, signed with your Signing Secret
`X-Elean-Event`	The event name, e.g. `task.created`

Verifying the signature

Compute an HMAC SHA-256 of the raw request body using your Signing Secret, and compare it (constant-time) to the X-Elean-Signature header:

import { createHmac, timingSafeEqual } from "crypto";

function isValidSignature(rawBody, signatureHeader, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

Always verify against the raw request body, before any JSON parsing — re-serializing the parsed body can change byte-for-byte formatting and break the signature check.

Supported events

Event	Description
`task.created`	A new task is created
`task.updated`	A task’s fields are edited
`task.assigned`	A task is assigned to someone
`task.status_changed`	A task moves to a different status
`task.priority_changed`	A task’s priority changes
`task.comment`	A new comment is posted on a task
`task.deleted`	A task is deleted

Retries

If your endpoint doesn’t respond with a 2xx status, elean retries with backoff up to your configured Max retry attempts (default 5).

Limits

The number of webhook connections per workspace depends on your plan:

Plan	Webhook connections
Free	3
Pro	15
Business	Unlimited

Disconnecting

Remove a connection from Workspace Settings → Integrations → Custom Webhook → Disconnect. No further events will be sent, and you can reconnect at any time.

Getting started

AI agents (MCP)

Integrations

Custom Webhook

Setup

Payload

Verifying the signature

Supported events

Retries

Limits

Disconnecting

​Setup

​Payload

​Verifying the signature

​Supported events

​Retries

​Limits

​Disconnecting

Setup

Payload

Verifying the signature

Supported events

Retries

Limits

Disconnecting