# 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.