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": "example@email.com",
                    "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": "example@email.com",
                    "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": "example@email.com",
                    "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": "example@email.com",
                    "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": "example@email.com",
                    "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": "example@email.com",
                    "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": "example@email.com",
                    "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": "example@email.com",
                    "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": "example@email.com",
                    "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.