Webhooks

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

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 — An example of a webhook configuration in awork

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.

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:

1 {
2     "timestamp": "2023-09-03T20:28:39.5966465+00:00",
3     "eventType": "project_added",
4     "entity": {
5         "id": "8293ac0e-0aaa-468c-b3fc-480b2d7200f0",
6         "hasImage": false,
7         "createdOn": "2023-09-03T20:28:39.5961826Z",
8         "createdBy": "7936d6b8-3345-4770-83c8-2c8c2ed12414",
9         "updatedOn": "2023-09-03T20:28:40.017585Z",
10         "updatedBy": "7936d6b8-3345-4770-83c8-2c8c2ed12414",
11         "projectStatus": {
12             "typeOrder": 2,
13             "isArchived": false,
14             "type": "not-started",
15             "name": "Not started",
16             "id": "fb7de344-aa95-4d75-ae1b-c7c01393f267"
17         },
18         "tags": ["design"],
19         "plannedDuration": 0,
20         "tasksCount": 0,
21         "tasksDoneCount": 0,
22         "members": [
23             {
24                 "id": "043a32e9-1a41-48d0-9e05-e5967ea849cc",
25                 "userId": "7936d6b8-3345-4770-83c8-2c8c2ed12414",
26                 "firstName": "Carla",
27                 "lastName": "Creative",
28                 "hasImage": false,
29                 "projectRoleId": "021e1b6b-3ba3-47ea-a829-141ca1686e7a",
30                 "projectRoleName": "Project Member",
31                 "isResponsible": true,
32                 "isDeactivated": false
33             }
34         ],
35         "trackedDuration": 0,
36         "teams": [],
37         "projectStatusId": "fb7de344-aa95-4d75-ae1b-c7c01393f267",
38         "name": "Website Design",
39         "isPrivate": false,
40         "timeBudget": 0,
41         "isBillableByDefault": false
42     },
43     "entityId": "8293ac0e-0aaa-468c-b3fc-480b2d7200f0",
44     "entityType": "project",
45     "entityLink": "https://superstar-design.awork.com/projects/8293ac0e-0aaa-468c-b3fc-480b2d7200f0",
46     "traceId": "5a8e9540f698455b48cd092811ade4e9",
47     "triggeredBy": {
48         "id": "7936d6b8-3345-4770-83c8-2c8c2ed12414",
49         "firstName": "Carla",
50         "lastName": "Creative"
51     },
52     "changes": [
53         {
54             "property": "ClosedBy",
55             "new": "a56c2b28-9dab-4f1a-b0b1-70aec2a68326"
56         },
57         {
58             "property": "ClosedOn",
59             "new": "02/02/2025 17:34:39"
60         },
61         {
62             "property": "TaskStatusId",
63             "old": "9481af0f-9307-467f-b2e1-f8586e9cd0da",
64             "new": "784e6fec-6c9a-ed11-bf7a-38563d6e68b8"
65         },
66         {
67             "property": "UpdatedOn",
68             "old": "01/22/2025 16:23:06",
69             "new": "02/02/2025 17:34:39"
70         }
71     ],
72 }

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.