cvat/site/content/en/docs/administration/advanced/webhooks.md

title	linkTitle	description	weight
Webhooks	Webhooks	Instructions for working with CVAT Webhooks	80

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.

In order to create webhook via an API call, see the swagger documentation. And also see examples of creating webhooks in our REST API tests.

Create Webhook for project

To create webhook for CVAT project, follow the steps:

Project -> Actions -> Setup Webhooks

Create Webhook for organization

To create webhook for CVAT organization, follow the steps:

Organization -> Settings -> Actions -> Setup Webhooks

List of available events

Resource	Create	Update	Delete
Organization		✅
Membership		✅	✅
Invitation	✅		✅
Project	✅	✅	✅
Task	✅	✅	✅
Job		✅
Issue	✅	✅	✅
Comment	✅	✅	✅

Payloads

Create event

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

Here is example of payload for create:task event: {{< scroll-code lang="json" >}} { "event": "create:task", "task": { "url": "http://localhost:8080/api/tasks/15", "id": 15, "name": "task", "project_id": 7, "mode": "", "owner": { "url": "http://localhost:8080/api/users/1", "id": 1, "username": "admin1", "first_name": "Admin", "last_name": "First" }, "assignee": null, "bug_tracker": "", "created_date": "2022-10-04T08:05:50.419259Z", "updated_date": "2022-10-04T08:05:50.422917Z", "overlap": null, "segment_size": 0, "status": "annotation", "labels": [ { "id": 28, "name": "label_0", "color": "#bde94a", "attributes": [], "type": "any", "sublabels": [], "has_parent": false } ], "segments": [], "dimension": "2d", "subset": "", "organization": null, "target_storage": { "id": 14, "location": "local", "cloud_storage_id": null }, "source_storage": { "id": 13, "location": "local", "cloud_storage_id": null } }, "webhook_id": 7, "sender": { "url": "http://localhost:8080/api/users/1", "id": 1, "username": "admin1", "first_name": "Admin", "last_name": "First" } } {{< /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

{{< scroll-code lang="json" >}} { "event": "update:task", "task": { "url": "http://localhost:8080/api/tasks/15", "id": 15, "name": "new task name", "project_id": 7, "mode": "annotation", "owner": { "url": "http://localhost:8080/api/users/1", "id": 1, "username": "admin1", "first_name": "Admin", "last_name": "First" }, "assignee": null, "bug_tracker": "", "created_date": "2022-10-04T08:05:50.419259Z", "updated_date": "2022-10-04T11:04:51.451681Z", "overlap": 0, "segment_size": 1, "status": "annotation", "labels": [ { "id": 28, "name": "label_0", "color": "#bde94a", "attributes": [], "type": "any", "sublabels": [], "has_parent": false } ], "segments": [ { "start_frame": 0, "stop_frame": 0, "jobs": [ { "url": "http://localhost:8080/api/jobs/19", "id": 19, "assignee": null, "status": "annotation", "stage": "annotation", "state": "new" } ] } ], "data_chunk_size": 14, "data_compressed_chunk_type": "imageset", "data_original_chunk_type": "imageset", "size": 1, "image_quality": 70, "data": 14, "dimension": "2d", "subset": "", "organization": null, "target_storage": { "id": 14, "location": "local", "cloud_storage_id": null }, "source_storage": { "id": 13, "location": "local", "cloud_storage_id": null } }, "before_update": { "name": "task" }, "webhook_id": 7, "sender": { "url": "http://localhost:8080/api/users/1", "id": 1, "username": "admin1", "first_name": "Admin", "last_name": "First" } } {{< /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

Here is example of payload for delete:task event: {{< scroll-code lang="json" >}} { "event": "delete:task", "task": { "url": "http://localhost:8080/api/tasks/15", "id": 15, "name": "task", "project_id": 7, "mode": "", "owner": { "url": "http://localhost:8080/api/users/1", "id": 1, "username": "admin1", "first_name": "Admin", "last_name": "First" }, "assignee": null, "bug_tracker": "", "created_date": "2022-10-04T08:05:50.419259Z", "updated_date": "2022-10-04T08:05:50.422917Z", "overlap": null, "segment_size": 0, "status": "annotation", "labels": [ { "id": 28, "name": "label_0", "color": "#bde94a", "attributes": [], "type": "any", "sublabels": [], "has_parent": false } ], "segments": [], "dimension": "2d", "subset": "", "organization": null, "target_storage": { "id": 14, "location": "local", "cloud_storage_id": null }, "source_storage": { "id": 13, "location": "local", "cloud_storage_id": null } }, "webhook_id": 7, "sender": { "url": "http://localhost:8080/api/users/1", "id": 1, "username": "admin1", "first_name": "Admin", "last_name": "First" } } {{< /scroll-code >}}

Webhook secret

To be ensure that webhooks come from CVAT you can specify secret when creating a webhook.

If you specified secret value for webhook, then CVAT will sent webhook with X-Signature-256 in request header.

CVAT encode request body for webhook using SHA256 hash function and put the result into the header.

Webhook receiver can check that request came from CVAT by comparison received value of X-Signature-256 with expected.

Example of header value for empty request body and secret = mykey:

X-Signature-256: e1b24265bf2e0b20c81837993b4f1415f7b68c503114d100a40601eca6a2745f

Ping Webhook

To check that webhook configured well and CVAT can connect with target URL you can use ping webhook.

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.

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

{{< scroll-code lang="json" >}} { "event": "ping", "webhook": { "id": 7, "url": "http://localhost:8080/api/webhooks/7", "target_url": "https://example.com", "description": "", "type": "project", "content_type": "application/json", "is_active": true, "enable_ssl": true, "created_date": "2022-10-04T08:05:23.007381Z", "updated_date": "2022-10-04T08:05:23.007395Z", "owner": { "url": "http://localhost:8080/api/users/1", "id": 1, "username": "admin1", "first_name": "Admin", "last_name": "First" }, "project": 7, "organization": null, "events": [ "create:comment", "create:issue", "create:task", "delete:comment", "delete:issue", "delete:task", "update:comment", "update:issue", "update:job", "update:project", "update:task" ], "last_status": 200, "last_delivery_date": "2022-10-04T11:04:52.538638Z" }, "sender": { "url": "http://localhost:8080/api/users/1", "id": 1, "username": "admin1", "first_name": "Admin", "last_name": "First" } } {{< /scroll-code >}}