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.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.
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_updated |
absence_deleted |
client_added |
client_updated |
client_deleted |
project_added |
project_updated |
project_comment_added |
project_deleted |
projectmember_added |
projectmember_deleted |
project_status_changed |
project_task_added |
project_task_deleted |
taskassignment_added |
taskassignment_deleted |
task_updated |
task_comment_added |
task_list_added |
task_list_updated |
task_list_deleted |
task_status_changed |
timetracking_added |
timetracking_updated |
timetracking_deleted |
user_activation_changed |
user_added |
user_deleted |
user_status_changed |
You can now trigger a test event to your configured URL.
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:{
"timestamp": "2023-09-03T20:28:39.5966465+00:00",
"eventType": "project_added",
"entity": {
"id": "8293ac0e-0aaa-468c-b3fc-480b2d7200f0",
"hasImage": false,
"createdOn": "2023-09-03T20:28:39.5961826Z",
"createdBy": "7936d6b8-3345-4770-83c8-2c8c2ed12414",
"updatedOn": "2023-09-03T20:28:40.017585Z",
"updatedBy": "7936d6b8-3345-4770-83c8-2c8c2ed12414",
"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": "043a32e9-1a41-48d0-9e05-e5967ea849cc",
"userId": "7936d6b8-3345-4770-83c8-2c8c2ed12414",
"firstName": "Carla",
"lastName": "Creative",
"hasImage": false,
"projectRoleId": "021e1b6b-3ba3-47ea-a829-141ca1686e7a",
"projectRoleName": "Project Member",
"isResponsible": true,
"isDeactivated": false
}
],
"trackedDuration": 0,
"teams": [],
"projectStatusId": "fb7de344-aa95-4d75-ae1b-c7c01393f267",
"name": "Website Design",
"isPrivate": false,
"timeBudget": 0,
"isBillableByDefault": false
},
"entityId": "8293ac0e-0aaa-468c-b3fc-480b2d7200f0",
"entityType": "project",
"entityLink": "https://superstar-design.awork.com/projects/8293ac0e-0aaa-468c-b3fc-480b2d7200f0",
"traceId": "5a8e9540f698455b48cd092811ade4e9",
"triggeredBy": {
"id": "7936d6b8-3345-4770-83c8-2c8c2ed12414",
"firstName": "Carla",
"lastName": "Creative"
}
}
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 Endpoint documentation. |
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. |
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.
Last modified 28d ago