Skip to content

C
Cvat

疯人忠 / Cvat

通知 1
Star 0
Fork 0
C
Cvat

体验新版 GitCode，发现更多精彩内容 >>

未验证 提交 62334912 编写于 作者: M Mariia Acoca 提交者： GitHub
浏览文件
操作

webhooks documentation updated (#6246) 

<!-- Raise an issue to propose your change
(https://github.com/opencv/cvat/issues).
It helps to avoid duplication of efforts from multiple independent
contributors.
Discuss your ideas with maintainers to be sure that changes will be
approved and merged.
Read the [Contribution
guide](https://opencv.github.io/cvat/docs/contributing/). -->

<!-- Provide a general summary of your changes in the Title above -->

### Motivation and context
<!-- Why is this change required? What problem does it solve? If it
fixes an open
issue, please link to the issue here. Describe your changes in detail,
add
screenshots. -->

### How has this been tested?
<!-- Please describe in detail how you tested your changes.
Include details of your testing environment, and the tests you ran to
see how your change affects other areas of the code, etc. -->

### Checklist
<!-- Go over all the following points, and put an `x` in all the boxes
that apply.
If an item isn't applicable for some reason, then ~~explicitly
strikethrough~~ the whole
line. If you don't do that, GitHub will show incorrect progress for the
pull request.
If you're unsure about any of these, don't hesitate to ask. We're here
to help! -->
- [ ] I submit my changes into the `develop` branch
- [ ] I have added a description of my changes into the
[CHANGELOG](https://github.com/opencv/cvat/blob/develop/CHANGELOG.md)
file
- [ ] I have updated the documentation accordingly
- [ ] I have added tests to cover my changes
- [ ] I have linked related issues (see [GitHub docs](

https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword))
- [ ] I have increased versions of npm packages if it is necessary

([cvat-canvas](https://github.com/opencv/cvat/tree/develop/cvat-canvas#versioning),

[cvat-core](https://github.com/opencv/cvat/tree/develop/cvat-core#versioning),

[cvat-data](https://github.com/opencv/cvat/tree/develop/cvat-data#versioning)
and

[cvat-ui](https://github.com/opencv/cvat/tree/develop/cvat-ui#versioning))

### License

- [ ] I submit _my code changes_ under the same [MIT License](
https://github.com/opencv/cvat/blob/develop/LICENSE) that covers the
project.
  Feel free to contact the maintainers if that's a concern.
上级 cb207b66
隐藏空白更改
内联 并排
Showing with 176 addition and 62 deletion
site/content/en/docs/administration/advanced/webhooks.md
浏览文件 @ 62334912
---
title: 'Webhooks'
linkTitle: 'Webhooks'
description: 'Instructions for working with CVAT Webhooks'
description: 'CVAT Webhooks: set up and use'
weight: 80
---
Webhooks are user-defined HTTP callbacks that are triggered by specific events.
When an event that triggers a webhook occurs, CVAT makes an HTTP request
to the URL configured for the webhook.
The request will include a payload with information about the event.
CVAT, webhooks can be triggered by a variety of events,
such as the creation, deletion, or modification of tasks,
jobs, and so on.
This makes it easy to set up automated processes
that respond to changes made in CVAT.
For example, you can set up webhooks to alert you when a job's assignee is changed or when
a job/task's status is updated, for instance, when a job is completed and ready for review
or has been reviewed. New task creation can also trigger notifications.
These capabilities allow you to keep track of progress and changes in your CVAT workflow instantly.
In CVAT you can create a webhook for a project or organization.
You can use CVAT GUI or direct API calls.
See:
- [Create Webhook](#create-webhook)
- [For project](#for-project)
- [For organization](#for-organization)
- [Webhooks forms](#webhooks-forms)
- [List of events](#list-of-events)
- [Payloads](#payloads)
- [Create event](#create-event)
- [Update event](#update-event)
- [Delete event](#delete-event)
- [Webhook secret](#webhook-secret)
- [Ping Webhook](#ping-webhook)
- [Webhooks with API calls](#webhooks-with-api-calls)
- [Example of setup and use](#example-of-setup-and-use)
## Create Webhook
In CVAT you can create webhook for project or for organization.
For creation, you can use our user interface or direct API calls.
### For project
To create a webhook for **Project**, do the following:
1. [Create a Project](/docs/manual/advanced/projects/).
2. Go to the **Projects** and click on the project's widget.
3. In the top right corner, click **Actions** > **Setup Webhooks**.
4. In the top right corner click **+**
![Create Project Webhook](/images/create_project_webhook.gif)
5. Fill in the **[Setup webhook](#webhooks-forms)** form and click **Submit**.
### For organization
To create a webhook for **Organization**, do the following:
1. [Create Organization](/docs/manual/advanced/organization/)
2. Go to the **Organization** > **Settings** > **Actions** > **Setup Webhooks**.
3. In the top right corner click **+**
![](/images/create_organization_webhook.gif)
In order to create webhook via an API call, see the [swagger documentation](https://app.cvat.ai/api/docs).
And also see examples of creating webhooks in our [REST API tests](https://github.com/opencv/cvat/blob/develop/tests/python/rest_api/test_webhooks.py).
4. Fill in the **[Setup webhook](#webhooks-forms)** form and click **Submit**.
### Create Webhook for project
### Webhooks forms
To create webhook for CVAT project, follow the steps:
The **Setup a webhook** forms look like the following.
`Project -> Actions -> Setup Webhooks`
![Create Project And Org Webhook Forms ](/images/webhook_form_project_org.jpg)
![](/images/create_project_webhook.gif)
Forms have the following fields:
### Create Webhook for organization
<!--lint disable maximum-line-length-->
To create webhook for CVAT organization, follow the steps:
| Field | Description |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Target URL | The URL where the event data will be sent. |
| Description | Provides a brief summary of the webhook's purpose. |
| Project | A drop-down list that lets you select from available projects. |
| Content type | Defines the data type for the payload in the webhook request via the HTTP Content-Type field. |
| Secret | A unique key for verifying the webhook's origin, ensuring it's genuinely from CVAT. <br>For more information, see [Webhook secret](#webhook-secret) |
| Enable SSL | A checkbox for enabling or disabling [SSL verification](https://en.wikipedia.org/wiki/Public_key_certificate). |
| Active | Uncheck this box if you want to stop the delivery of specific webhook payloads. |
| Send everything | Check this box to send all event types through the webhook. |
| Specify individual events | Choose this option to send only certain event types. <br>Refer to the [List of available events](#list-of-available-events) for more information on event types. |
`Organization -> Settings -> Actions -> Setup Webhooks`
<!--lint enable maximum-line-length-->
![](/images/create_organization_webhook.gif)
### List of events
## List of available events
The following events are available for webhook alerts.
| Resource | Create | Update | Delete |
| :---: | :----: | :----: | :----: |
| Organization | | ✅ | |
| Membership | | ✅ | ✅ |
| Invitation | ✅ | | ✅ |
| Project | ✅ | ✅ | ✅ |
| Task | ✅ | ✅ | ✅ |
| Job | | ✅ | |
| Issue | ✅ | ✅ | ✅ |
| Comment | ✅ | ✅ | ✅ |
<!--lint disable maximum-line-length-->
| Resource | Create | Update | Delete | Description |
| ------------ | ------ | ------ | ------ | ----------------------------------------------------------------------------------- |
| Organization | | ✅ | | Alerts for changes made to an Organization. |
| Membership | | ✅ | ✅ | Alerts when a member is added to or removed from an organization. |
| Invitation | ✅ | | ✅ | Alerts when an invitation to an Organization is issued or revoked. |
| Project | ✅ | ✅ | ✅ | Alerts for any actions taken within a project. |
| Task | ✅ | ✅ | ✅ | Alerts for actions related to a task, such as status changes, assignments, etc. |
| Job | | ✅ | | Alerts for any updates made to a job. |
| Issue | ✅ | ✅ | ✅ | Alerts for any activities involving issues. |
| Comment | ✅ | ✅ | ✅ | Alerts for actions involving comments, such as creation, deletion, or modification. |
<!--lint enable maximum-line-length-->
## Payloads
......@@ -48,17 +117,22 @@ To create webhook for CVAT organization, follow the steps:
Webhook payload object for `create:<resource>` events:
| Key | Type | Description |
| :---: | :----: | :---- |
| `event` | `string` | Name of event that triggered webhook with pattern `create:<resource>` |
| `<resource>` | `object` | Full information about created resource. See the swagger docs for each separate resource |
| `webhook_id` | `integer` | Identifier of webhook that sent payload |
| `sender` | `object` | Information about user that triggered webhook |
<!--lint disable maximum-line-length-->
| Key | Type | Description |
| ------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `event` | `string` | Identifies the event that triggered the webhook, following the `create:<resource>` pattern. |
| `<resource>` | `object` | Complete information about the created resource. Refer to the [Swagger](#webhooks-with-api-calls) docs for individual resource details. |
| `webhook_id` | `integer` | The identifier for the webhook that sends the payload. |
| `sender` | `object` | Details about the user that triggered the webhook. |
<!--lint enable maximum-line-length-->
An example of payload for the `create:task` event:
Here is example of payload for `create:task` event:
{{< scroll-code lang="json" >}}
{
"event": "create:task",
"event": "create:task",
"task": {
"url": "<http://localhost:8080/api/tasks/15>",
"id": 15,
......@@ -116,18 +190,23 @@ Here is example of payload for `create:task` event:
}
{{< /scroll-code >}}
### Update event
Webhook payload object for `update:<resource>` events:
| Key | Type | Description |
| :---: | :----: | :---- |
| `event` | `string` | Name of event that triggered webhook with pattern `update:<resource>` |
| `<resource>` | `object` | Full information about updated resource. See the swagger docs for each separate resource |
| `before_update` | `object` | Keys of `<resource>` that was updated with theirs old values |
| `webhook_id` | `integer` | Identifier of webhook that sent payload |
| `sender` | `object` | Information about user that triggered webhook |
<!--lint disable maximum-line-length-->
| Key | Type | Description |
| --------------- | --------- | ---------------------------------------------------------------------------------------------------- |
| `event` | `string` | Identifies the event that triggered the webhook, following the `update:<resource>` pattern. |
| `<resource>` | `object` | Provides complete information about the updated resource. See the Swagger docs for resource details. |
| `before_update` | `object` | Contains keys of `<resource>` that were updated, along with their old values. |
| `webhook_id` | `integer` | The identifier for the webhook that dispatched the payload. |
| `sender` | `object` | Details about the user that triggered the webhook. |
<!--lint enable maximum-line-length-->
An example of `update:<resource>` event:
{{< scroll-code lang="json" >}}
{
......@@ -212,18 +291,24 @@ Webhook payload object for `update:<resource>` events:
}
}
{{< /scroll-code >}}
### Delete event
Webhook payload object for `delete:<resource>` events:
| Key | Type | Description |
| :---: | :----: | :---- |
| `event` | `string` | Name of event that triggered webhook with pattern `delete:<resource>` |
| `<resource>` | `object` | Full information about deleted resource. See the swagger docs for each separate resource |
| `webhook_id` | `integer` | Identifier of webhook that sent payload |
| `sender` | `object` | Information about user that triggered webhook |
<!--lint disable maximum-line-length-->
| Key | Type | Description |
| ------------ | --------- | ---------------------------------------------------------------------------------------------------- |
| `event` | `string` | Identifies the event that triggered the webhook, following the `delete:<resource>` pattern. |
| `<resource>` | `object` | Provides complete information about the deleted resource. See the Swagger docs for resource details. |
| `webhook_id` | `integer` | The identifier for the webhook that dispatched the payload. |
| `sender` | `object` | Details about the user that triggered the webhook. |
<!--lint enable maximum-line-length-->
Here is an example of the payload for the `delete:task` event:
Here is example of payload for `delete:task` event:
{{< scroll-code lang="json" >}}
{
"event": "delete:task",
......@@ -286,16 +371,17 @@ Here is example of payload for `delete:task` event:
## Webhook secret
To be ensure that webhooks come from CVAT you can specify `secret` when creating a webhook.
To validate that the webhook requests originate from CVAT, include a `secret` during the webhook creation process.
If you specified `secret` value for webhook, then CVAT will sent webhook with `X-Signature-256` in
request header.
When a `secret` is provided for the webhook, CVAT includes an `X-Signature-256` in the request header of the webhook.
CVAT encode request body for webhook using SHA256 hash function and put the result into the header.
CVAT uses the SHA256 hash function to encode the request
body for the webhook and places the resulting hash into the header.
Webhook receiver can check that request came from CVAT by comparison received value of `X-Signature-256` with expected.
The webhook recipient can verify the source of the request
by comparing the received `X-Signature-256` value with the expected value.
Example of header value for empty request body and `secret = mykey`:
Here's an example of a header value for a request with an empty body and `secret = mykey`:
```
X-Signature-256: e1b24265bf2e0b20c81837993b4f1415f7b68c503114d100a40601eca6a2745f
......@@ -327,22 +413,31 @@ def webhook():
## Ping Webhook
To check that webhook configured well and CVAT can connect with target URL you can use `ping` webhook.
To confirm the proper configuration of your webhook and ensure that CVAT can establish
a connection with the target URL, use the **Ping** webhook feature.
![Ping Webhook ](/images/ping_webhook.jpg)
After pressing `Ping` bottom on UI (or sending `POST /webhooks/{id}/ping` request) CVAT will sent webhook
to the target url with general information about webhook.
1. Click the **Ping** button in the user interface (or send a `POST /webhooks/{id}/ping` request through API).
2. CVAT will send a webhook alert to the specified target URL with basic information about the webhook.
Ping webhook payload:
| Key | Type | Description |
| :---: | :----: | :---- |
| `event` | `string` | Value always equals `ping` |
| `webhook` | `object` | Full information about webhook. See the full description of webhook`s fields in swagger docs |
| `sender` | `object` | Information about user that called `ping` webhook |
<!--lint disable maximum-line-length-->
| Key | Type | Description |
| --------- | -------- | -------------------------------------------------------------------------------------------------- |
| `event` | `string` | The value is always `ping`. |
| `webhook` | `object` | Complete information about the webhook. See the Swagger docs for a detailed description of fields. |
| `sender` | `object` | Information about the user who initiated the `ping` on the webhook. |
<!--lint enable maximum-line-length-->
Here is an example of a payload for the `ping` event:
{{< scroll-code lang="json" >}}
{
"event": "ping",
"event": "ping",
"webhook": {
"id": 7,
"url": "<http://localhost:8080/api/webhooks/7>",
......@@ -388,3 +483,22 @@ Ping webhook payload:
}
}
{{< /scroll-code >}}
## Webhooks with API calls
To create webhook via an API call,
see [Swagger documentation](https://app.cvat.ai/api/docs).
For examples,
see [REST API tests](https://github.com/opencv/cvat/blob/develop/tests/python/rest_api/test_webhooks.py).
## Example of setup and use
This video demonstrates setting up email alerts for a project using Zapier and Gmail.
<!--lint disable maximum-line-length-->
<iframe width="560" height="315" src="https://www.youtube.com/embed/x87CsGsd-3I" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
<!--lint enable maximum-line-length-->
site/content/en/images/ping_webhook.jpg 0 → 100644
浏览文件 @ 62334912
此差异由.gitattributes 抑制。
site/content/en/images/webhook_form_project_org.jpg 0 → 100644
浏览文件 @ 62334912
此差异由.gitattributes 抑制。
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或