> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.awork.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.awork.com/_mcp/server.

# Webhooks

> Learn how to configure and receive webhooks in awork.

Webhooks allow application developers to receive and react to changes happening in awork without constantly polling and checking.

# Workspace Webhooks

A webhook is triggered for an entire workspace. For example on the `project-added` webhook, you receive events for all projects created in your workspace, no matter who created it or which team it belongs to. This means that user permissions and roles are not checked and have to be evaluated by the developer, if relevant.

## Configuration

To configure a webhook, go to your awork workspace, navigate to *Settings* > *Integrations*, then open the *Integration Library* and select *Webhooks*.

You are then asked to provide a name and the URL for the webhook. Authorization information is optional and can be added to the webhook request as a header where you can specify the header name and value.

![Webhook Config](/_fern-img/c0a083c752316d9c8bd7bf58ded55a10c129ffb0c8a36fc7870e0884d7237436.webp)

Finally, select the events you want this webhook to trigger on. The following event types are supported:

| Event Type                  |
| --------------------------- |
| `absence_added`             |
| `absence_deleted`           |
| `absence_updated`           |
| `company_added`             |
| `company_deleted`           |
| `company_type_changed`      |
| `company_updated`           |
| `project_added`             |
| `project_comment_added`     |
| `project_deleted`           |
| `projectmember_added`       |
| `projectmember_deleted`     |
| `project_status_changed`    |
| `project_type_changed`      |
| `project_updated`           |
| `task_added`                |
| `taskassignment_added`      |
| `taskassignment_deleted`    |
| `task_comment_added`        |
| `task_deleted`              |
| `tasklist_added`            |
| `tasklist_deleted`          |
| `tasklist_updated`          |
| `task_status_changed`       |
| `task_type_changed`         |
| `task_updated`              |
| `timetracking_added`        |
| `timetracking_deleted`      |
| `timetracking_type_changed` |
| `timetracking_updated`      |
| `user_activation_changed`   |
| `user_added`                |
| `user_deleted`              |
| `user_status_changed`       |
| `user_updated`              |

You can now trigger a test event to your configured URL.

For more details, please take a look at our [Help Center](https://support.awork.com/en/articles/webhooks-CqjKq3O26bV4).

## Receiving a Webhook

When the configured event occurs, awork will send an HTTP `POST` request to the configured URL. It will contain the configured authorization header and value, if set.

The request body will contain the event metadata as well as the entity that triggered the event. For the `project-added` event, this can look like in this example:

```json
{
    "timestamp": "2025-07-24T14:28:39.5966465+00:00",
    "eventType": "project_added",
    "entity": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "hasImage": false,
        "createdOn": "2023-09-03T20:28:39.5961826Z",
        "createdBy": "123e4567-e89b-12d3-a456-426614174000",
        "updatedOn": "2025-07-24T14:28:40.017585Z",
        "updatedBy": "123e4567-e89b-12d3-a456-426614174000",
        "projectStatus": {
            "typeOrder": 2,
            "isArchived": false,
            "type": "not-started",
            "name": "Not started",
            "id": "fb7de344-aa95-4d75-ae1b-c7c01393f267"
        },
        "tags": ["design"],
        "plannedDuration": 0,
        "tasksCount": 0,
        "tasksDoneCount": 0,
        "members": [
            {
                "id": "123e4567-e89b-12d3-a456-426614174000",
                "userId": "123e4567-e89b-12d3-a456-426614174000",
                "firstName": "Carla",
                "lastName": "Creative",
                "hasImage": false,
                "projectRoleId": "123e4567-e89b-12d3-a456-426614174000",
                "projectRoleName": "Project Member",
                "isResponsible": true,
                "isDeactivated": false
            }
        ],
        "trackedDuration": 0,
        "teams": [],
        "projectStatusId": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Website Design",
        "isPrivate": false,
        "timeBudget": 0,
        "isBillableByDefault": false
    },
    "entityId": "123e4567-e89b-12d3-a456-426614174000",
    "entityType": "project",
    "entityLink": "https://superstar-design.awork.com/projects/123e4567-e89b-12d3-a456-426614174000",
    "traceId": "5a8e9540f698455b48cd092811ade4e9",
    "triggeredBy": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "firstName": "Carla",
        "lastName": "Creative"
    },
    "changes": [
        {
            "property": "ClosedBy",
            "new": "123e4567-e89b-12d3-a456-426614174000"
        },
        {
            "property": "ClosedOn",
            "new": "2025-07-24T14:28:39.5966465+00:00"
        },
        {
            "property": "TaskStatusId",
            "old": "123e4567-e89b-12d3-a456-426614174000",
            "new": "123e4567-e89b-12d3-a456-426614174001"
        },
        {
            "property": "UpdatedOn",
            "old": "2025-07-24T14:28:39.5966465+00:00",
            "new": "2025-07-24T14:28:39.5966465+00:00"
        }
    ],
}
```

Events of type `deleted` use the same metadata structure. The returned entity can include additional deletion metadata, such as `deletedOn` and `deletedBy`, depending on the entity model:

```json
{
    "eventType": "absence_deleted",
    "entity": {
        "...": "...",
        "deletedOn": "2025-07-24T14:28:39.5966465+00:00",
        "deletedBy": "123e4567-e89b-12d3-a456-426614174000"
    }
}
```

| Metadata Property | Description                                                                                                                                                                                                           |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `timestamp`       | The date and time this event was triggered.                                                                                                                                                                           |
| `eventType`       | The type of event that was triggered. See table of event types above.                                                                                                                                                 |
| `entity`          | The entity that was responsible for triggering the event, for example the project that was added. For more information on the properties of the entity, please refer to the model documentation in the API reference. |
| `entityId`        | The id of the entity that triggered the event.                                                                                                                                                                        |
| `entityType`      | The type of entity that triggered the event.                                                                                                                                                                          |
| `entityLink`      | The weblink to the entity that triggered the event, or the closest entity that has a weblink, where available.                                                                                                        |
| `traceId`         | An awork-internal id for support purposes.                                                                                                                                                                            |
| `triggeredBy`     | The id, first and last name of the user that triggered the event.                                                                                                                                                     |
| `changes`         | A list of changes, including property name, old and new value. Not always available!                                                                                                                                  |

## Responding to a Webhook

awork expects a webhook request to return with a successful response within 30 seconds. Otherwise, the event will be marked as failed and retried for up to 10 times.

Should a configured webhook integration fail for more than 10 times without a successful response, it will be paused until a user enables it again in the Integration settings page.

# Project Automation Webhooks

Project automation webhooks can be configured as actions for project automations. Read more about project automations in our [Help Center](https://support.awork.com/en/articles/automations-in-projects-8Y349YeytvNV).

## Configuration

This type automation action requires a URL where the payload will be sent to. Optionally, users can configure a custom event name as well as a header name and value for athentication.

![Project Automation Webhook Config](/_fern-img/6391aa9fcad156087707ca57ca16d37120284007037ce58294ae41f96027856b.webp)

## Example

| Property             | Value                         |
| -------------------- | ----------------------------- |
| URL                  | `https://example.com/webhook` |
| Event Name           | `Task Status Changed`         |
| Authorization Header | Api-Key:abcd...               |

This will result in the following request to the provided URL when the automation trigger occurs:

**`Webhook Request`**

```sh title="Webhook Request"
curl -X POST https://example.com/webhook \
  -H 'Content-Type: application/json' \
  -H 'Api-Key: abcd...' \
  -d '{
        "eventName": "Task Status Changed",
        "traceId": "5a8e9540f698455b48cd092811ade4e9",
        "project": {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            ...
        },
        "task": {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            ...
        }
      }'
```

The webhook body will contain the following properties:

| Payload Property | Description                                                                                                                                       |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eventName`      | The user-provided name of the event.                                                                                                              |
| `traceId`        | An awork-internal id for support purposes.                                                                                                        |
| `project`        | The project this automation belongs to. [Model details](/apiv1/projects/get-project-by-id).                                                       |
| `task`           | The task that triggered the automation. Can be empty if the automation was not triggered by a task. [Model details](/apiv1/tasks/get-task-by-id). |