---
title: Webhook API
slug: webhook-api
docTags: 
createdAt: 2024-05-13T15:13:50.014Z
---

Webhooks are a way for web applications to get real-time notifications when events occur. Catenda APIs support webhooks to allow you to subscribe to events that occur in the Catenda platform.

They are particularly useful for asynchronous events like when a new topic is created or updated.

When creating any webhooks you will need to provide a URL where the webhook events will be sent. This URL must be publicly accessible and respond with a `200 OK` status code to the webhook events. Examples of platforms that can be used to receive and handle webhook events are [Zapier](https://zapier.com/) and [RequestBin](https://requestbin.com/).

# Creating a webhook

To create a webhook use the create webhook endpoint with the following parameters.

| Name         | Type   | Description                                |
| ------------ | ------ | ------------------------------------------ |
| `event`      | String | The event to subscribe to                  |
| `target_url` | String | The URL to be called when the event occurs |

Anytime the event occurs the target URL will be called with the event data.

Supported events are:

- `issue.created`: A topic is created.
- `issue.deleted`: A topic is deleted.
- `issue.modified`: A topic is updated.
- `issue.status.changed`: The status of a topic is updated.
- `library.document.revision.published`: A document revision is created.
- `model.created`: A model is created.
- `revision.created`: A model revision is created.

# Receiving a webhook event

When an event occurs Catenda will send a `POST` request to the target URL with the event and any project data related to the event.

| Name           | Type   | Description                                                                |
| -------------- | ------ | -------------------------------------------------------------------------- |
| `event`        | Object | The event that ocurred                                                     |
| `project`      | Object | The project the event occurred in                                          |
| `issue`        | Object | The topic involved in the event                                            |
| `libraryItem`  | Object | The document library item involved in the event if applicable              |
| `model`        | Object | The model involved in the event                                            |
| `modification` | Object | The modification involved in the event, applies to `issue.modified` events |
| `revision`     | Object | The revision involved in the event                                         |
| `created_by`   | Object | The user that created the event                                            |

**event**

The event that occurred.

| Name        | Type   | Description                |
| ----------- | ------ | -------------------------- |
| `id`        | String | The id of the event        |
| `type`      | String | The type of the event      |
| `timestamp` | String | The timestamp of the event |

**modification**

The modification involved in the event, applies to `issue.modified` events

Supported modification event types are:

- `assigned_to_removed`
- `assigned_to_updated`
- `comment_created`
- `description_updated`
- `due_date_updated`
- `due_date_removed`
- `labels_added`
- `labels_removed`
- `priority_updated`
- `status_updated`
- `title_updated`
- `type_updated`
- `viewpoint_created`

| Name         | Type   | Description                                 |
| ------------ | ------ | ------------------------------------------- |
| `event`      | String | The modification event that occurred        |
| `modifiedBy` | Object | The user involved in the modification event |
| `type`       | String | The modification event type                 |
| `value`      | String | The new value                               |