Guide to the V7 Webhook format
One of the most useful stages when creating custom workflows is the V7 webhook stage. It allows you to send the annotation payload and associated metadata of an item at any point in a workflow to an endpoint of your choosing. This can then be parsed by a serverless function or equivalent to accomplish a great number of use cases from realtime notifications to automated ontology checking and QA. Combined with our darwin-py SDK and REST API, you can really customize your workflow to your specific needs. In this doc, we will discuss the structure of the webhook payload to help you get the most out of this powerful tool.
Webhook Payload Size
Be sure that the endpoint dealing with your webhooks can handle files of the size you expect otherwise you will get a 413 error. This should especially be considered when sending webhooks for videos
Payload Structure
The webhook annotation data will be in the same format as that for a Darwin JSON 2.0 export but the metadata has a slightly different structure.
The webhook metadata includes:
- team slug and team name
- dataset slug and dataset name
- item id
- item information including as V7 item name and V7 path
- slot information including slot number, height and width of the slot file and the name of the slot
- source information about the original files including a presigned url to external storage the external storage file/V7 stored file
Below is an example payload including metadata and the annotation data for a selection of common annotation formats:
{
"annotations": [
{
"annotators": [
{
"email": "[email protected]",
"full_name": "Example User"
}
],
"bounding_box": {
"h": 242,
"w": 251,
"x": 177,
"y": 99
},
"id": "778192d5-86af-4a4e-8c48-9afe827a243a",
"name": "test_polygon",
"polygon": {
"paths": [
[
{
"x": 324,
"y": 334
},
{
"x": 334,
"y": 329
},
{
"x": 335,
"y": 327
},
{
"x": 336,
"y": 327
},
{
"x": 342,
"y": 322
},
{
"x": 349,
"y": 318
},
{
"x": 349,
"y": 303
},
{
"x": 350,
"y": 302
},
{
"x": 350,
"y": 300
},
{
"x": 354,
"y": 297
},
{
"x": 363,
"y": 297
},
{
"x": 365,
"y": 296
},
{
"x": 365,
"y": 292
},
{
"x": 362,
"y": 289
},
{
"x": 357,
"y": 287
},
{
"x": 356,
"y": 285
},
{
"x": 361,
"y": 281
},
{
"x": 367,
"y": 280
},
{
"x": 369,
"y": 278
},
{
"x": 369,
"y": 274
},
{
"x": 372,
"y": 270
},
{
"x": 377,
"y": 270
},
{
"x": 379,
"y": 272
},
{
"x": 387,
"y": 273
},
{
"x": 387,
"y": 267
},
{
"x": 386,
"y": 266
},
{
"x": 386,
"y": 263
},
{
"x": 385,
"y": 262
},
{
"x": 385,
"y": 258
},
{
"x": 388,
"y": 255
},
{
"x": 392,
"y": 253
},
{
"x": 397,
"y": 253
},
{
"x": 398,
"y": 252
},
{
"x": 402,
"y": 252
},
{
"x": 403,
"y": 253
},
{
"x": 406,
"y": 253
},
{
"x": 407,
"y": 255
},
{
"x": 410,
"y": 255
},
{
"x": 410,
"y": 253
},
{
"x": 409,
"y": 252
},
{
"x": 410,
"y": 250
},
{
"x": 412,
"y": 248
},
{
"x": 413,
"y": 248
},
{
"x": 413,
"y": 243
},
{
"x": 411,
"y": 240
},
{
"x": 411,
"y": 237
},
{
"x": 407,
"y": 231
},
{
"x": 407,
"y": 228
},
{
"x": 409,
"y": 226
},
{
"x": 414,
"y": 226
},
{
"x": 415,
"y": 225
},
{
"x": 417,
"y": 225
},
{
"x": 428,
"y": 215
},
{
"x": 428,
"y": 210
}
]
]
},
"reviewers": [],
"slot_names": [
"0"
],
"updated_at": "2023-07-11T11:06:00"
},
{
"annotators": [
{
"email": "[email protected]",
"full_name": "Example User"
}
],
"bounding_box": {
"h": 105.4,
"w": 139.05,
"x": 78.1,
"y": 52.7
},
"id": "e2827f79-abfd-4261-b28c-42025303a16d",
"name": "test_bbox",
"reviewers": [],
"slot_names": [
"0"
],
"updated_at": "2023-07-11T11:06:06"
},
{
"annotators": [
{
"email": "[email protected]",
"full_name": "Example User"
}
],
"id": "4a7ef2e4-e6c9-4304-9207-b6aa4cddb383",
"keypoint": {
"x": 484.44,
"y": 88.89
},
"name": "test_keypoint",
"reviewers": [],
"slot_names": [
"0"
],
"updated_at": "2023-07-11T11:06:09"
},
{
"annotators": [
{
"email": "[email protected]",
"full_name": "Example User"
}
],
"id": "cc4b3da6-1194-4883-871c-e00c43496bdc",
"keypoint": {
"x": 479.37,
"y": 151.11
},
"name": "test_keypoint",
"reviewers": [],
"slot_names": [
"0"
],
"updated_at": "2023-07-11T11:06:11"
},
{
"annotators": [
{
"email": "[email protected]",
"full_name": "Example User"
}
],
"id": "87e127c0-3d5c-480c-93de-b6d3fd1cbbce",
"line": {
"path": [
{
"x": 86.98,
"y": 236.83
},
{
"x": 118.1,
"y": 360
},
{
"x": 177.78,
"y": 379.05
},
{
"x": 255.87,
"y": 400
},
{
"x": 351.11,
"y": 387.3
},
{
"x": 473.65,
"y": 384.13
},
{
"x": 561.27,
"y": 378.41
}
]
},
"name": "test_line",
"reviewers": [],
"slot_names": [
"0"
],
"updated_at": "2023-07-11T11:06:22"
},
{
"annotators": [
{
"email": "[email protected]",
"full_name": "Example User"
}
],
"ellipse": {
"angle": 0.65,
"center": {
"x": 340.32,
"y": 45.4
},
"radius": {
"x": 28.76,
"y": 28.76
}
},
"id": "0aa8804f-e229-4dc0-8c22-b5db771cfeb3",
"name": "test_ellipse",
"reviewers": [],
"slot_names": [
"0"
],
"updated_at": "2023-07-11T11:06:56"
},
{
"annotators": [
{
"email": "[email protected]",
"full_name": "Example User"
}
],
"cuboid": {
"back": {
"h": 0.63,
"w": 9.52,
"x": 528.89,
"y": 286.98
},
"front": {
"h": 57.14,
"w": 61.59,
"x": 488.25,
"y": 219.05
}
},
"id": "354c919a-ef6f-4a64-bc5d-16fce29ce5c8",
"name": "test_cuboid",
"reviewers": [],
"slot_names": [
"0"
],
"updated_at": "2023-07-11T11:07:01"
},
{
"annotators": [
{
"email": "[email protected]",
"full_name": "Example User"
}
],
"id": "2083c090-f8e4-47c1-8a1f-1e2bd17a96f0",
"name": "test_skeleton",
"reviewers": [],
"skeleton": {
"nodes": [
{
"name": "1",
"occluded": false,
"x": 500.49,
"y": 439.83
},
{
"name": "2",
"occluded": false,
"x": 513.36,
"y": 425.17
},
{
"name": "3",
"occluded": false,
"x": 559.34,
"y": 425.59
},
{
"name": "4",
"occluded": false,
"x": 576.97,
"y": 441.65
},
{
"name": "5",
"occluded": false,
"x": 577.69,
"y": 413.71
}
]
},
"slot_names": [
"0"
],
"updated_at": "2023-07-11T11:07:11"
},
{
"annotators": [
{
"email": "[email protected]",
"full_name": "Example User"
}
],
"id": "d0aca77d-f73d-4940-8368-f1098d6aab40",
"name": "test_tag",
"reviewers": [],
"slot_names": [
"0"
],
"tag": {},
"updated_at": "2023-07-11T11:07:19"
}
],
"item": {
"name": "exampleimage.jpg",
"path": "/",
"slots": [
{
"height": 480,
"slot_name": "0",
"source_files": [
{
"file_name": "exampleimage.jpg",
"url": "https://darwin.v7labs.com/s/data/teams/2327/partition_487/0189449f-8284-731e-b28c-63aff7eb0a54/uploads/0fc03827-9338-4bdf-bde5-d6b9c74c941a.jpg?token=SFMyNTY.eyJleHAiOjE2ODkxMTA3MTEsImtleV9wcmVmaXgiOiJkYXRhL3RlYW1zLzIzMjcvcGFydGl0aW9uXzQ4Ny8wMTg5NDQ5Zi04Mjg0LTczMWUtYjI4Yy02M2FmZjdlYjBhNTQvdXBsb2Fkcy8wZmMwMzgyNy05MzM4LTRiZGYtYmRlNS1kNmI5Yzc0Yzk0MWEuanBnIn0.ogklkDXUMbIkeBuae0QGz9DtMw_pZ0DIv3PpRB3qCUg"
}
],
"thumbnail_url": "https://darwin.v7labs.com/s/data/teams/2327/partition_487/0189449f-8284-731e-b28c-63aff7eb0a54/uploads/0fc03827-9338-4bdf-bde5-d6b9c74c941a.jpg/thumbnails/1.jpg?token=SFMyNTY.eyJleHAiOjE2ODkxMTA2NzQsImtleV9wcmVmaXgiOiJkYXRhL3RlYW1zLzIzMjcvcGFydGl0aW9uXzQ4Ny8wMTg5NDQ5Zi04Mjg0LTczMWUtYjI4Yy02M2FmZjdlYjBhNTQvdXBsb2Fkcy8wZmMwMzgyNy05MzM4LTRiZGYtYmRlNS1kNmI5Yzc0Yzk0MWEuanBnL3RodW1ibmFpbHMvMS5qcGcifQ.eEeVCoiP-9dtb5vl3JPRRst2vlXt7lC1O4ONF4dvO5w",
"type": "image",
"width": 640
}
],
"source_info": {
"dataset": {
"dataset_management_url": "https://darwin.v7labs.com/datasets/657571/dataset-management",
"name": "Example Dataset",
"slug": "example-dataset"
},
"item_id": "0189449f-8284-731e-b28c-63aff7eb0a54",
"team": {
"name": "Example Team",
"slug": "example-team"
},
"workview_url": "https://darwin.v7labs.com/workview?dataset=657571&item=0189449f-8284-731e-b28c-63aff7eb0a54"
}
},
"schema_ref": "https://darwin-public.s3.eu-west-1.amazonaws.com/darwin_json_2_0.schema.json",
"version": "2.0"
}
Authorization
When setting up the webhook in the UI, you will have the ability to add an optional (but strongly recommended!) authorization header to your webhook request.
If additionally you would like to allow requests from IP addresses defined by your ACL then please reach out to your CSM or our Support team who will provide you with next steps.