Webhooks

Webhooks allow you to register, via the API, a webhook that you can use to receive notifications about key events in your account.

The API currently supports the following events:

Event type	Description
`project.created`	Fires when a new project is created
`project.updated`	Fires when a project is updated
`time.entry.created`	Fires when a new time entry is created
`time.entry.updated`	Fires when a time entry is updated
`user.created`	Fires when a new time entry is created
`user.updated`	Fires when a user is updated
`assignment.created`	Fires when a new assignment is created
`assignment.updated`	Fires when an assignment is updated

Endpoints

The following endpoints are available for managing webhooks.

GET /api/v1/webhooks
POST /api/v1/webhooks
GET /api/v1/webhooks/<webhook_id>
DELETE /api/v1/webhooks/<webhook_id>

Note: Updating an existing webhook is currently unavailable.

Required parameters

Parameter	Description
url	The URL to which events should be posted. Must be HTTPS with a valid host.
event_type	The type of event to subscribe to. For example, `project.created`

Key concepts

Webhook status

Currently, the only valid status for a webhook is active. This field is reserved for future extensions of the webhooks API.

Webhook limits

To prevent the repeated posting of the same webhook payload, no more than 10 webhooks are allowed per event type.

Webhook payloads

When you register a webhook for a particular event type, a POST request is made to the webhook URL containing data about the affected object. Additionally, the webhook payload has a data field with the object details and a type field indicating the event that occurred.

A webhook payload looks like this:

{
    "data": {
      [ data about the object ]
    },
    "type": [event type]
}

Note: The data in the payload is exactly the same as what would be returned from a GET call for the object, with no additional fields. To get additional data, it's recommended that you make a separate GET request using the object ID from the payload.

Updated event triggers

When an updated event fires, the payload is the same as a created event. Some changes don't trigger an updated event.

Assignments: Any permitted change to an assignment, such as dates, allocation mode, percent, etc., triggers an updated event.
Note: Changing the assignee triggers an assignment.deleted followed by an assignment.created event.
Time entries: Any permitted change, such as hours or notes, triggers an updated event.
Projects: Basic property changes, such as name, dates, etc., trigger update events. The following changes don't trigger updated events:
- Creating assignments
- Changing budgets or bill rates
- Adding or editing tags and custom fields
Users: Basic property changes (name, email, etc.), role, discipline, location changes, and availability and bill rate changes trigger updated events.
Note: Creating assignments for users on a project changes doesn't trigger updated events.