Webhooks

Managing the webhooks described under Webhook deliveries above. A webhook belongs to the person who created it: nobody else can list, change or delete it, or read its delivery log.

List webhook events

GET /api/v2/webhooks/events · beta

Lists the events a webhook can subscribe to.

Any signed-in member of the workspace may call it. Answers with data: the list of event names a webhook can subscribe to.


Auth	Session or API token with the `read` scope
Token limited to projects	Refused

Request

http

GET /api/v2/webhooks/events
Authorization: Bearer <token>
companyid: <company id>

Response

json

{
  "status": true,
  "statusText": "Webhook events.",
  "data": ["task.created", "task.updated", "task.deleted", "task.archived", "task.restored"]
}

Errors

Status	When
401	No token, a token that is invalid, expired or revoked, or no valid `companyid` header.
403	The token lacks the `read` scope, or its person is no longer a member of the workspace. A token limited to projects is refused here.
429	Too many requests from this address. Wait `retryAfter` seconds and send it again.

List webhooks

GET /api/v2/webhooks · beta

Lists the caller's own webhooks. The signing secret is never returned here.

Any signed-in member of the workspace may call it. Answers with data: the webhooks the caller created, together with any recorded with no owner, each with name, url, events, active, format, lastStatus, lastDeliveredAt, needsAttention and createdAt, and never the secret.


Auth	Session or API token with the `read` scope
Token limited to projects	Refused

Request

http

GET /api/v2/webhooks
Authorization: Bearer <token>
companyid: <company id>

Response

json

{
  "status": true,
  "statusText": "Webhooks fetched.",
  "data": [
    {
      "_id": "<webhook id>",
      "name": "Release channel",
      "url": "https://hooks.example.com/alianhub",
      "events": ["task.created", "task.updated"],
      "active": true,
      "format": "json",
      "createdBy": "<user id>",
      "createdAt": "2026-10-01T09:30:00.000Z",
      "lastStatus": 200,
      "lastDeliveredAt": "2026-10-01T09:30:00.000Z",
      "needsAttention": ""
    }
  ]
}

Paging

None. The whole list is returned.

Errors

Status	When
401	No token, a token that is invalid, expired or revoked, or no valid `companyid` header.
403	The token lacks the `read` scope, or its person is no longer a member of the workspace. A token limited to projects is refused here.
429	Too many requests from this address. Wait `retryAfter` seconds and send it again.

Create a webhook

POST /api/v2/webhooks · beta

Creates a webhook and returns its signing secret, once.

Any signed-in member of the workspace may call it. Reads name (string), url (string), events (string list) and format (string) from the body. The address must be an http or https one that resolves to a public host, or to a private host the person who runs the server allows. Failures answer a failed status with the reason. Answers with data: the webhook and its secret, shown once.


Auth	Session or API token with the `write` scope
Token limited to projects	Refused

Body

Field	Type	Required	Description
`name`	string	yes	Up to 80 characters.
`url`	string	yes	An `http` or `https` address on a public host.
`events`	string[]	yes	At least one event, or `*` for all of them.
`format`	string		`json` (the default), `slack` or `discord`.

Request

http

POST /api/v2/webhooks
Authorization: Bearer <token>
companyid: <company id>
Content-Type: application/json

{
  "name": "Release channel",
  "url": "https://hooks.example.com/alianhub",
  "events": ["task.created", "task.updated"]
}

Response

json

{
  "status": true,
  "statusText": "Webhook created. Store the secret now — it is not shown again.",
  "data": {
    "_id": "<webhook id>",
    "name": "Release channel",
    "url": "https://hooks.example.com/alianhub",
    "events": ["task.created", "task.updated"],
    "active": true,
    "format": "json",
    "createdBy": "<user id>",
    "createdAt": "2026-10-01T09:30:00.000Z",
    "secret": "<signing secret>"
  }
}

Errors

Status	When
400	No name, a name over 80 characters, an address that is not `http` or `https` or does not resolve to a public host, no events, an unknown event, or an unknown format.
401	No token, a token that is invalid, expired or revoked, or no valid `companyid` header.
403	The token lacks the `write` scope, or its person is no longer a member of the workspace. A token limited to projects is refused here.
429	Too many requests from this address. Wait `retryAfter` seconds and send it again.

Change a webhook

PUT /api/v2/webhooks/:id · beta

Changes a webhook, or switches it on or off. Only the keys sent are changed.

Any signed-in member of the workspace may call it, on a webhook the caller created or one recorded with no owner; any other id answers Webhook not found.. Reads name, url, events, format and active from the body and changes the ones sent; a body with none of them answers Nothing to update.. A new url is checked as when creating. Answers with data: the webhook as it is now.


Auth	Session or API token with the `write` scope
Token limited to projects	Refused

Path parameters

Name	Type	Description
`id`	id	The webhook.

Body

Field	Type	Description
`name`	string	Up to 80 characters.
`url`	string	An `http` or `https` address on a public host.
`events`	string[]	Replaces the events.
`format`	string	`json`, `slack` or `discord`.
`active`	boolean	`false` stops deliveries; `true` starts them again.

Request

http

PUT /api/v2/webhooks/<id>
Authorization: Bearer <token>
companyid: <company id>
Content-Type: application/json

{ "active": false }

Response

json

{
  "status": true,
  "statusText": "Webhook updated.",
  "data": {
    "_id": "<webhook id>",
    "name": "Release channel",
    "url": "https://hooks.example.com/alianhub",
    "events": ["task.created", "task.updated"],
    "active": false,
    "format": "json",
    "createdBy": "<user id>",
    "createdAt": "2026-10-01T09:30:00.000Z"
  }
}

Errors

Status	When
400	The id is not an id, a value is not accepted, or the body names nothing to change.
401	No token, a token that is invalid, expired or revoked, or no valid `companyid` header.
403	The token lacks the `write` scope, or its person is no longer a member of the workspace. A token limited to projects is refused here.
404	The webhook does not exist, or is someone else's.
429	Too many requests from this address. Wait `retryAfter` seconds and send it again.

Delete a webhook

DELETE /api/v2/webhooks/:id · beta

Deletes a webhook, its delivery log and its signing secret.

Any signed-in member of the workspace may call it, on a webhook the caller created or one recorded with no owner; any other id answers Webhook not found.. Removes the webhook, its delivery log and its signing secret. Answers with statusText Webhook deleted. and no data.


Auth	Session or API token with the `write` scope
Token limited to projects	Refused

Path parameters

Name	Type	Description
`id`	id	The webhook.

Request

http

DELETE /api/v2/webhooks/<id>
Authorization: Bearer <token>
companyid: <company id>

Response

json

{ "status": true, "statusText": "Webhook deleted." }

Errors

Status	When
400	The id is not an id.
401	No token, a token that is invalid, expired or revoked, or no valid `companyid` header.
403	The token lacks the `write` scope, or its person is no longer a member of the workspace. A token limited to projects is refused here.
404	The webhook does not exist, or is someone else's.
429	Too many requests from this address. Wait `retryAfter` seconds and send it again.

Read a webhook's delivery log

GET /api/v2/webhooks/:id/logs · beta

Lists a webhook's deliveries, newest first.

Any signed-in member of the workspace may call it, on a webhook the caller created or one recorded with no owner; any other id answers Webhook not found.. Reads limit (1 to 50, 10 when left out) and skip (0 or more) from the query. Answers with data (the deliveries, newest first), hasMore and nextSkip.


Auth	Session or API token with the `read` scope
Token limited to projects	Refused

Path parameters

Name	Type	Description
`id`	id	The webhook.

Query parameters

Name	Type	Required	Description
`limit`	number		How many rows to return, from 1 to 50. 10 when left out.
`skip`	number		How many rows to pass over. 0 when left out.

Request

http

GET /api/v2/webhooks/<id>/logs?limit=10&skip=0
Authorization: Bearer <token>
companyid: <company id>

Response

json

{
  "status": true,
  "statusText": "Delivery log fetched.",
  "data": [
    {
      "_id": "<log id>",
      "webhookId": "<webhook id>",
      "event": "task.updated",
      "statusCode": 200,
      "success": true,
      "durationMs": 180,
      "attempt": 1,
      "createdAt": "2026-10-01T09:30:00.000Z"
    }
  ],
  "hasMore": true,
  "nextSkip": 10
}

Paging

Skip and limit. hasMore and nextSkip sit beside data; send nextSkip back as skip while hasMore is true.

Errors

Status	When
400	The id is not an id.
401	No token, a token that is invalid, expired or revoked, or no valid `companyid` header.
403	The token lacks the `read` scope, or its person is no longer a member of the workspace. A token limited to projects is refused here.
404	The webhook does not exist, or is someone else's.
429	Too many requests from this address. Wait `retryAfter` seconds and send it again.

Webhooks ​

List webhook events ​

List webhooks ​

Create a webhook ​

Change a webhook ​

Delete a webhook ​

Read a webhook's delivery log ​

Webhooks

List webhook events

List webhooks

Create a webhook

Change a webhook

Delete a webhook

Read a webhook's delivery log