Webhooks

Open In Colab

GitHub

See Webhooks guide page for details on how to use webhooks to receive notifications from activities in Labelbox.

Example configurations to receive requests

from flask import Flask, request
import json
import hmac
import hashlib
import threading
from werkzeug.serving import run_simple

# This can be any secret that matches your webhook config (we will set later)
secret = b"<replace with secret>"

# Example for server-side code to receive webhook events
app = Flask(__name__)


@app.route("/webhook-endpoint", methods=["POST"])
def print_webhook_info():
    payload = request.data
    computed_signature = hmac.new(
        secret, msg=payload, digestmod=hashlib.sha1
    ).hexdigest()
    if request.headers["X-Hub-Signature"] != "sha1=" + computed_signature:
        print(
            "Error: computed_signature does not match signature provided in the headers"
        )
        return "Error", 500

    print("=========== New Webhook Delivery ============")
    print("Delivery ID: %s" % request.headers["X-Labelbox-Id"])
    print("Event: %s" % request.headers["X-Labelbox-Event"])
    print(
        "Payload: %s"
        % json.dumps(json.loads(payload.decode("utf8")), indent=4)
    )
    return "Success"


thread = threading.Thread(
    target=lambda: run_simple("0.0.0.0", 3001, app)
)
thread.start()

import hmac
import hashlib
import re

secret = "<replace with secret>"

# Example of a AWS Lambda to receive webhook events
def lambda_handler(event, context):
    webhook = re.sub(
        r"^sha1=",
        "",
        event["headers"]["x-hub-signature"],
    )

    digest = hmac.new(
        key=bytes(secret, "utf-8"),
        msg=event["body"].encode("utf-8"),
        digestmod=hashlib.sha1,
    )

    if webhook != digest.hexdigest():
        return {
            "statusCode": 400,
            "body": "Error: computed_signature does not match",
        }

    print("=========== New Webhook Delivery ============")
    print("Delivery ID: %s" % event["headers"]["x-labelbox-id"])
    print("Event: %s" % event["headers"]["x-labelbox-event"])
    print("=========== Payload =============")
    print(event["body"])
    return "Success"

import functions_framework
import json
import hmac
import hashlib

secret = b"<replace with secret>"

# Example of a Google Cloud Function to receive webhook events
@functions_framework.http
def hello_http(request):
    payload = request.data
    computed_signature = hmac.new(
        secret, msg=payload, digestmod=hashlib.sha1
    ).hexdigest()
    if request.headers["X-Hub-Signature"] != "sha1=" + computed_signature:
        print(
            "Error: computed_signature does not match signature provided in the headers"
        )
        return "Error", 500

    print("=========== New Webhook Delivery ============")
    print("Delivery ID: %s" % request.headers["X-Labelbox-Id"])
    print("Event: %s" % request.headers["X-Labelbox-Event"])
    print(
        "Payload: %s"
        % json.dumps(json.loads(payload.decode("utf8")), indent=4)
    )
    return "Success"

import azure.functions as func
import json
import hmac
import logging
import hashlib

secret = b"<replace with secret>"

# Example of an Azure Function to receive webhook events
app = func.FunctionApp(http_auth_level=func.AuthLevel.FUNCTION)

@app.route(route="http_trigger")
def http_trigger(req: func.HttpRequest) -> func.HttpResponse:
    payload = req.get_body()
    computed_signature = hmac.new(
        secret, msg=payload, digestmod=hashlib.sha1
    ).hexdigest()
    if req.headers["X-Hub-Signature"] != "sha1=" + computed_signature:
        logging.warning(
            "Error: computed_signature does not match signature provided in the headers"
        )
        return func.HttpResponse("Error", status_code=500)

    logging.info("=========== New Webhook Delivery ============")
    logging.info("Delivery ID: %s" % req.headers["X-Labelbox-Id"])
    logging.info("Event: %s" % req.headers["X-Labelbox-Event"])
    logging.info(
        "Payload: %s"
        % json.dumps(json.loads(payload.decode("utf8")), indent=4)
    )
    return func.HttpResponse("Success", status_code=200)

Create webhook

Webhook v2 setup

You can create a v2 webhook through the Labelbox UI. The v2 webhook mimics the export payload.

Webhook v1 setup

As shown below, you can create a v1 webhook with the Python SDK or the Labelbox UI, which is similar to v2 webhooks.

from labelbox import Client, Webhook

public_url = "https://example.com/webhook-endpoint" # Your server's public url - where the messages will be sent to
secret = b"CHANGE-ME" # Use to verify Labelbox is sending the message

client = Client(api_key="<YOUR_API_KEY>")
project = client.get_project("<project_id>")
print([topic.value for topic in Webhook.Topic]) # See all available topics
secret = b"example_secret" # This can be any secret that matches your webhook config (we will set later)

webhook = Webhook.create(client,
topics=["LABEL_CREATED"],
url="public_url",
secret=secret.decode(),
project=project)

Get webhooks

# Fetch all webhooks
org = client.get_organization()
webhooks = org.webhooks() #paginated

# Fetch project webhooks
project = client.get_project("<project_id>")
webhooks = project.webhooks()  #paginated

webhook = next(webhooks)
status = webhook.status
server_url = webhook.url
topics = webhook.topics
project = webhook.project()

Update webhook

# url, topics, and status can all be updated
updated_url = f"{public_url}/webhook-endpoint"
webhook.update(url=updated_url, topics=[Topic.LABEL_DELETED], status=Webhook.Status.INACTIVE.value)

Delete webhook

webhook.delete()

Sample response

v2

{
  "data_row": {
    "id": "clvmpaetz76ct0706730rfcq9",
    "external_id": null,
    "global_key": "TEST-ID-157128604429964085398241585654637789196d",
    "row_data": "https://storage.googleapis.com/labelbox-datasets/People_Clothing_Segmentation/jpeg_images/IMAGES/img_0001.jpeg",
    "metadata_fields": [],
    "details": {
      "dataset_id": "clvmpa9et010j0750rlgs8qdi",
      "created_at": "2024-04-30T18:07:10.82Z",
      "updated_at": "2024-04-30T18:07:14.199Z",
      "created_by": null
    }
  },
  "projects": {
    "clvo7ajpc014907zxagiw9hry": {
      "project_name": "test_lambda",
      "labels": [
        {
          "label_kind": "Default",
          "id": "clvo7b6h501ic07fdbg62c32w",
          "label_details": {
            "created_at": "2024-05-06T17:18:48Z",
            "updated_at": "2024-05-06T17:18:48Z",
            "created_by": "[email protected]"
          },
          "performance_details": {
            "seconds_to_create": 5759.536,
            "seconds_to_review": 0,
            "skipped": false,
            "benchmark_reference_label": null,
            "benchmark_score": null,
            "consensus_score": null
          },
          "annotations": {
            "classifications": [],
            "objects": [
              {
                "bbox": {
                  "height": 359,
                  "left": 24,
                  "top": 85,
                  "width": 480
                },
                "color": "#1976d2",
                "feature_id": "clvv876mw00023b6qr6mk2o4s",
                "instance_uri": "https://api.labelbox.com/masks/feature/clvv876mw00023b6qr6mk2o4s",
                "schema_id": "clvcnmppk0aq507z11haa4x66",
                "title": "person",
                "value": "person"
              }
            ],
            "relationships": []
          }
        }
      ],
      "project_details": {
        "ontology_id": "clvcnmpor0aq207z14jesh8w7",
        "batch_id": "11EF07D4F9E60FC08820734F207E70B1",
        "priority": 5,
        "consensus_expected_label_count": {
          "Int32": 1,
          "Valid": true
        }
      }
    }
  },
  "media_attributes": {
    "asset_type": "image",
    "content_length": 122898,
    "exif_rotation": 1,
    "height": 825,
    "mime_type": "image/jpeg",
    "sub_type": "jpeg",
    "super_type": "image",
    "width": 550
  }
}

{
  "data_row": {
    "id": "clvmpaetz76ct0706730rfcq9",
    "external_id": null,
    "global_key": "TEST-ID-157128604429964085398241585654637789196d",
    "row_data": "https://storage.googleapis.com/labelbox-datasets/People_Clothing_Segmentation/jpeg_images/IMAGES/img_0001.jpeg",
    "metadata_fields": [],
    "details": {
      "dataset_id": "clvmpa9et010j0750rlgs8qdi",
      "created_at": "2024-04-30T18:07:10.82Z",
      "updated_at": "2024-04-30T18:07:14.199Z",
      "created_by": null
    }
  },
  "projects": {
    "clvo7ajpc014907zxagiw9hry": {
      "project_name": "test_lambda",
      "labels": [
        {
          "label_kind": "Default",
          "id": "clvo7b6h501ic07fdbg62c32w",
          "label_details": {
            "created_at": "2024-05-06T17:18:48Z",
            "updated_at": "2024-05-06T17:18:48Z",
            "created_by": "[email protected]"
          },
          "performance_details": {
            "seconds_to_create": 5759.536,
            "seconds_to_review": 0,
            "skipped": false,
            "benchmark_reference_label": null,
            "benchmark_score": null,
            "consensus_score": null
          },
          "annotations": {
            "classifications": [],
            "objects": [
              {
                "bbox": {
                  "height": 359,
                  "left": 24,
                  "top": 85,
                  "width": 480
                },
                "color": "#1976d2",
                "feature_id": "clvv876mw00023b6qr6mk2o4s",
                "instance_uri": "https://api.labelbox.com/masks/feature/clvv876mw00023b6qr6mk2o4s",
                "schema_id": "clvcnmppk0aq507z11haa4x66",
                "title": "person",
                "value": "person"
              }
            ],
            "relationships": []
          }
        }
      ],
      "project_details": {
        "ontology_id": "clvcnmpor0aq207z14jesh8w7",
        "batch_id": "11EF07D4F9E60FC08820734F207E70B1",
        "priority": 5,
        "consensus_expected_label_count": {
          "Int32": 1,
          "Valid": true
        }
      }
    }
  },
  "media_attributes": {
    "asset_type": "image",
    "content_length": 122898,
    "exif_rotation": 1,
    "height": 825,
    "mime_type": "image/jpeg",
    "sub_type": "jpeg",
    "super_type": "image",
    "width": 550
  }
}

{
  "data_row": {
    "id": "clvmpaetz76cp0706m3jw8ww4",
    "external_id": null,
    "global_key": "TEST-ID-157128695542350976802229818230180675596d",
    "row_data": "https://storage.googleapis.com/labelbox-datasets/People_Clothing_Segmentation/jpeg_images/IMAGES/img_0004.jpeg",
    "metadata_fields": [],
    "details": {
      "dataset_id": "clvmpa9et010j0750rlgs8qdi",
      "created_at": "2024-04-30T18:07:10.819Z",
      "updated_at": "2024-04-30T18:07:14.196Z",
      "created_by": null
    }
  },
  "projects": {
    "clvo7ajpc014907zxagiw9hry": {
      "project_name": "test_lambda",
      "labels": [
        {
          "label_kind": "Default",
          "id": "clvo7b02m01p807znd5bwfr2v",
          "label_details": {
            "created_at": "2024-05-01T19:19:31Z",
            "updated_at": "2024-05-06T17:22:06Z",
            "created_by": "[email protected]"
          },
          "performance_details": {
            "seconds_to_create": 3.75,
            "seconds_to_review": 0,
            "skipped": false,
            "benchmark_reference_label": null,
            "benchmark_score": null,
            "consensus_score": null
          },
          "annotations": {
            "classifications": [],
            "objects": [
              {
                "bbox": {
                  "height": 540,
                  "left": 130,
                  "top": 82,
                  "width": 311
                },
                "color": "#1976d2",
                "feature_id": "clvo7b6qr00023b6q4xe4nnff",
                "instance_uri": "https://api.labelbox.com/masks/feature/clvo7b6qr00023b6q4xe4nnff",
                "schema_id": "clvcnmppk0aq507z11haa4x66",
                "title": "person",
                "value": "person"
              }
            ],
            "relationships": []
          }
        }
      ],
      "project_details": {
        "ontology_id": "clvcnmpor0aq207z14jesh8w7",
        "batch_id": "11EF07D4F9E60FC08820734F207E70B1",
        "priority": 5,
        "consensus_expected_label_count": {
          "Int32": 1,
          "Valid": true
        }
      }
    }
  },
  "media_attributes": {
    "asset_type": "image",
    "content_length": 167155,
    "exif_rotation": 1,
    "height": 825,
    "mime_type": "image/jpeg",
    "sub_type": "jpeg",
    "super_type": "image",
    "width": 550
  }
}

{
  "organizationId": "cloordigw0091073kc6pohyab",
  "projectId": "clvo7ajpc014907zxagiw9hry",
  "action": "MOVE",
  "dataRowIds": ["clvmpaetz76ct0706730rfcq9"],
  "originTaskId": "b363420e-1ea9-09dd-914c-d105efc5785a",
  "originTaskName": "Initial labeling task",
  "destinationTaskId": "c7a8a45d-c37d-4dba-bde7-792581597b10",
  "destinationTaskName": "Initial review task",
  "actorId": "cloordihe0092073kcorncj7g",
  "timestamp": "2024-05-06T17:18:48.797Z"
}

v1

{
  "agreement": null,
  "benchmarkAgreement": null,
  "createdAt": "2023-02-13T18:22:46Z",
  "dataRow": {
    "createdAt": "2023-01-25T17:54:20Z",
    "deletedAt": null,
    "externalId": "multi_thread_update_4cfdcb29-be33-4e07-b586-849829385210",
    "id": "cldbyu7c7n4jp072scuqt66ll",
    "labelCountInProject": 1,
    "rowData": "https://labelbox.s3-us-west-2.amazonaws.com/datasets/mapillary_traffic/images/F1xqHzDSi1qP3qSLBXVyJQ.jpg",
    "updatedAt": "2023-01-25T20:42:57Z"
  },
  "dataset": {
    "createdAt": "2023-01-25T17:53:58Z",
    "deleted": false,
    "description": "",
    "id": "cldbytq0w2uw8074hgl3hbxr2",
    "name": "Datarow Update Test - 5K",
    "updatedAt": "2023-01-25T17:54:21Z"
  },
  "deleted": false,
  "id": "cle357uex0g5307z996y28ic0",
  "label": "{\"objects\":[{\"featureId\":\"cle357vrp00013b6jsi6dfei0\",\"schemaId\":\"cldan3u0701sc07yi6xyw6up6\",\"color\":\"#ff0000\",\"title\":\"bounding_box\",\"value\":\"bounding_box\",\"bbox\":{\"top\":453,\"left\":951,\"height\":670,\"width\":952},\"instanceURI\":\"https://api.labelbox.com/masks/feature/cle357vrp00013b6jsi6dfei0\"}],\"classifications\":[],\"relationships\":[]}",
  "project": {
    "createdAt": "2023-02-13T18:20:52Z",
    "deleted": false,
    "description": "",
    "id": "cle355i370h86070hf1v7ata1",
    "name": "Webhooks",
    "updatedAt": "2023-02-13T18:22:17Z"
  },
  "secondsToLabel": 0,
  "skipped": false,
  "updatedAt": "2023-02-13T18:22:46Z",
  "user": { "email": "[email protected]", "id": "clbpgxfaehww6076tedo5ejwx" }
}

{
  "id": "cl4g555g81ltr07cka1a2b1wv",
  "createdAt": "2022-06-16T19:41:49Z",
  "updatedAt": "2022-06-16T19:58:25Z",
  "secondsToLabel": 6.002,
  "label": "{\"objects\":[{\"featureId\":\"cl4hg2phm00013b6j2thsko0u\",\"schemaId\":\"cl2i6hbju1o2y10a321w3cusv\",\"title\":\"grape\",\"value\":\"grape\",\"color\":\"#1CE6FF\",\"bbox\":{\"top\":298,\"left\":445,\"height\":520,\"width\":930},\"instanceURI\":\"https://api.labelbox.com/masks/feature/cl4hg2phm00013b6j2thsko0u\"}],\"classifications\":[],\"relationships\":[]}",
  "agreement": null,
  "benchmarkAgreement": null,
  "deleted": false,
  "skipped": false,
  "labelCountInProject": 2,
  "project": {
    "id": "cl2i6gssn1o2210a3gq549fq0",
    "createdAt": "2022-04-27T22:57:43Z",
    "updatedAt": "2022-06-15T22:19:36Z",
    "name": "grapes",
    "description": "",
    "deleted": false
  },
  "dataRow": {
    "id": "cl2hzfg8g18kw0ztwbtnq0b6q",
    "createdAt": "2022-04-27T19:40:43Z",
    "updatedAt": "2022-04-27T20:13:51Z",
    "deletedAt": null,
    "externalId": "CFR_1620.jpg",
    "rowData": "https://storage.labelbox.com/ckhmnux5zeutm0825bt0kj34y%2F5375dc13-6442-22d7-f523-e9d252e715ea-CFR_1620.jpg?Expires=1656619105&KeyName=labelbox-assets-key-3&Signature=iOg3tbKe4j7xWZHw1r5rQD4iJIk="
  },
  "dataset": {
    "id": "cl2hz9qay0unl10a3f4wmcsfi",
    "createdAt": "2022-04-27T19:36:16Z",
    "updatedAt": "2022-04-27T19:40:43Z",
    "name": "data",
    "description": "",
    "deleted": false
  },
  "user": {
    "id": "ckhmnux6hi0p907898jext199",
    "email": "[email protected]"
  }
}

{
  "id": "cl2i6hegh1x660z9i9fzz01a0",
  "createdAt": "2022-04-27T22:58:35Z",
  "updatedAt": "2022-06-16T20:12:41Z",
  "secondsToLabel": 31.448,
  "label": "{\"objects\":[{\"featureId\":\"cl2i6hhgd00013f6ghfnrcn6h\",\"schemaId\":\"cl2i6hbju1o2y10a321w3cusv\",\"title\":\"grape\",\"value\":\"grape\",\"color\":\"#1CE6FF\",\"bbox\":{\"top\":701,\"left\":402,\"height\":316,\"width\":238},\"instanceURI\":\"https://api.labelbox.com/masks/feature/cl2i6hhgd00013f6ghfnrcn6h\"},{\"featureId\":\"cl2i6hp3h00033f6gaofl29lx\",\"schemaId\":\"cl2i6hbju1o3010a30ksn2yiy\",\"title\":\"grape mask\",\"value\":\"grape_mask\",\"color\":\"#FF34FF\",\"instanceURI\":\"https://api.labelbox.com/masks/feature/cl2i6hp3h00033f6gaofl29lx\"}],\"classifications\":[],\"relationships\":[]}",
  "agreement": null,
  "benchmarkAgreement": null,
  "deleted": true,
  "skipped": false,
  "labelCountInProject": 1,
  "project": {
    "id": "cl2i6gssn1o2210a3gq549fq0",
    "createdAt": "2022-04-27T22:57:43Z",
    "updatedAt": "2022-06-16T20:06:25Z",
    "name": "grapes",
    "description": "",
    "deleted": false
  },
  "dataRow": {
    "id": "cl2hzfg8g18kk0ztwg22ke4vz",
    "createdAt": "2022-04-27T19:40:43Z",
    "updatedAt": "2022-04-27T20:13:52Z",
    "deletedAt": null,
    "externalId": "SYH_2017-04-27_1324.jpg",
    "rowData": "https://storage.labelbox.com/ckhmnux5zeutm0825bt0kj34y%2F1d883928-046f-97d5-e3f7-e6c296967c7e-SYH_2017-04-27_1324.jpg?Expires=1656619961&KeyName=labelbox-assets-key-3&Signature=0ma5Yw5qxdJE6_x7ACR7aPEHePM="
  },
  "dataset": {
    "id": "cl2hz9qay0unl10a3f4wmcsfi",
    "createdAt": "2022-04-27T19:36:16Z",
    "updatedAt": "2022-04-27T19:40:43Z",
    "name": "data",
    "description": "",
    "deleted": false
  },
  "user": {
    "id": "ckhmnux6hi0p907898jext199",
    "email": "[email protected]"
  }
}

{
  "organizationId": "cl81imdtk0cie0yx4g39i0du8",
  "projectId": "clbxofp0h05d2074475g14f9v",
  "action": "APPROVE",
  "dataRowIds": ["cl9elx44f001i076k2pz84tw6"],
  "originTaskId": "92665e1f-a507-4308-bdfc-d6be3c629ec7",
  "originTaskName": "My custom review step",
  "destinationTaskId": null,
  "destinationTaskName": "Done",
  "actorId": "cl81imdtx0cif0yx4ak0ndq8a",
  "timestamp": "2023-01-20T12:06:01.421Z"
}

Delivery retries

When your endpoint does not answer a delivery with a 2xx status within 30 seconds, Labelbox sends it again 10 seconds, 30 seconds, and 90 seconds after the previous attempt: up to 3 retries, so at most 4 attempts. An error status, a timeout, and a failed connection all count as a failed attempt. After the fourth failed attempt Labelbox stops, and you can find the event in the webhook events list. A retry is the same request as the first attempt: the same body, the same X-Labelbox-Id and X-Labelbox-Event, and the same X-Hub-Signature and X-Hub-Signature-256. A retry also carries an X-Labelbox-Delivery-Attempt header with the attempt number, 2 to 4. The first attempt does not send this header.

Deduplicate by X-Labelbox-Id. If your endpoint processed an event but answered too late or with an error, it receives the event again. Skip the IDs you have already processed.
Answer quickly. Return a 2xx as soon as you have stored the event and do slow work afterwards, so that a delivery is not retried while you are still processing it.
Retries stop with the webhook. If the webhook is deactivated or deleted, the remaining retries of its events are not sent.
Best effort. A retry can occasionally be lost, for example while Labelbox deploys an update. The webhook events list has every event, whatever happened to its deliveries.

Delivery retries are rolling out gradually. Until they are on for your organization, Labelbox sends each event once, and every event in the webhook events list has a single attempt.

Catch up on missed events

If your endpoint was down or kept returning errors, it may have missed events, even after delivery retries. To find them, list your organization’s webhook events from the last 30 days, starting after the last event your endpoint processed, and process the ones you missed. The list shows what Labelbox sent: every event, with the payload and each attempt to deliver it, with the HTTP status your endpoint returned. Reading it does not send anything again.

Before you start

You need:

A Labelbox API key.
Permission to view webhooks in your organization, as the Admin and Read-only Admin roles have. Without it, the request is refused with 403.
The ID of the last event you processed. It is the X-Labelbox-Id header of that delivery, so keep it with each event you process.

The endpoint is a GET request, authenticated with your API key as a bearer token:

https://api.labelbox.com/api/v1/webhook-events

List events

Get the events sent to one webhook after an event you processed:

cURL

curl -H "Authorization: Bearer $LABELBOX_API_KEY" \
  "https://api.labelbox.com/api/v1/webhook-events?starting_after=$LAST_EVENT_ID&webhook_id=$WEBHOOK_ID&limit=100"

The response has the events in data, oldest first:

{
  "data": [
    {
      "id": "<EVENT_ID>",
      "created_at": "2026-10-19T09:14:03.000Z",
      "event_type": "LABEL_CREATED",
      "project_id": "<PROJECT_ID>",
      "webhook_id": "<WEBHOOK_ID>",
      "status_code": 503,
      "payload": {
        "data_row": { "id": "<DATA_ROW_ID>" },
        "projects": { "<PROJECT_ID>": { "project_name": "My project" } }
      },
      "attempts": [
        { "attempt": 1, "created_at": "2026-10-19T09:14:03.000Z", "status_code": 503 },
        { "attempt": 2, "created_at": "2026-10-19T09:14:13.000Z", "status_code": 200 }
      ]
    }
  ],
  "has_more": true,
  "next_cursor": "<EVENT_ID>"
}

Parameters

Parameter	Description
`starting_after`	An event ID. Only events after it are listed, not the event itself. Use the `X-Labelbox-Id` of a delivery, or the `next_cursor` of the previous page. The event must be from your organization, at least five minutes old, and from the last 30 days. Leave it out to start 30 days ago.
`limit`	Events per page, from 1 to 100. The default is 100.
`event_type`	Only events of this type, such as `LABEL_CREATED`.
`project_id`	Only events about this project. See `project_id` in Event fields for the payloads it matches.
`webhook_id`	Only events sent to this webhook.
`created_after`, `created_before`	Only events recorded in this time range, both included, as RFC 3339 timestamps such as `2026-10-19T09:00:00Z`. Both must be within the last 30 days, and `created_after` at least five minutes ago.

Any other parameter, or a parameter given more than once, is refused with 400.

Event fields

Field	Description
`id`	The event ID: the `X-Labelbox-Id` header Labelbox sent with the delivery. Use it to recognize events you already have.
`created_at`	When the first attempt was recorded, after your endpoint responded.
`event_type`	The `X-Labelbox-Event` header sent with the delivery, such as `LABEL_CREATED`.
`project_id`	The project in the payload: `project.id` in a v1 payload, or the key of `projects` in a v2 payload when there is only one. Otherwise `null`, for example for a workflow event, which the `project_id` filter does not match either. With the `project_id` filter, the project you asked for.
`webhook_id`	The webhook the event was sent to.
`status_code`	The HTTP status your endpoint returned to the first attempt. A delivery that got no response, for example because the connection failed or timed out, is recorded as `500`.
`payload`	The body that was sent, the same JSON your endpoint received.
`attempts`	Every attempt to deliver the event, first attempt first, each with `attempt` (`1` to `4`, the `X-Labelbox-Delivery-Attempt` that was sent), `created_at`, and `status_code`. An event that was not retried has one attempt, with the event’s own `created_at` and `status_code`. See Delivery retries.

Each webhook gets its own delivery of an event, with its own ID. If your organization has more than one webhook for the same events, filter by webhook_id to list only the deliveries to your endpoint.

Page through the events

Events come in the order of their IDs, which is the order they were sent. Request pages until has_more is false, passing the next_cursor of each page as the starting_after of the next, with the same filters. next_cursor is null on the last page. With event_type, project_id, created_after, or created_before, one request examines at most 5,000 events. If it reaches that limit before it fills the page, it returns the events it found, possibly none, with has_more true. next_cursor is then the last event it examined, which may not be in data. Keep paging: an empty page does not mean you have reached the end. This example processes every event sent to your webhook after the last one you processed, and returns the ID to start from next time:

Python

import requests

API_URL = "https://api.labelbox.com/api/v1/webhook-events"
HEADERS = {"Authorization": "Bearer <YOUR_API_KEY>"}


def catch_up(last_event_id, webhook_id):
    params = {
        "starting_after": last_event_id,
        "webhook_id": webhook_id,
        "limit": 100,
    }
    while True:
        response = requests.get(API_URL, headers=HEADERS, params=params, timeout=60)
        response.raise_for_status()
        page = response.json()
        for event in page["data"]:
            process(event["id"], event["event_type"], event["payload"])  # your own handler
            last_event_id = event["id"]
        if not page["has_more"]:
            return last_event_id
        params["starting_after"] = page["next_cursor"]

Your endpoint may also have received some of these events. Skip the IDs you have already processed.

Data freshness and limits

Five minutes behind. An event is listed about five minutes after it was sent. Events from the last five minutes are not listed yet, and an event ID cannot be used as starting_after until it is five minutes old.
Slow endpoints. An event is recorded only after your endpoint responds. If your endpoint took longer than five minutes to respond, the event can be listed after you have already paged past its ID.
30 days. Only events from the last 30 days are listed. An older event ID is refused with 400: start again with created_after instead.

Errors

Status	Meaning
`400`	A parameter is invalid or not supported, or `starting_after` is not an event ID from your organization that is at least five minutes old and from the last 30 days. The response’s `message` says which. It is also returned if your organization has more than 5,000 webhooks.
`401`	The API key is missing or invalid.
`403`	You do not have permission to view webhooks.

Getting started

Annotate

Model

Catalog

Schema

Import/Export

Integrations

Manage Team

Examples

Open In Colab

GitHub

Example configurations to receive requests

Create webhook

Webhook v2 setup

Webhook v1 setup

Get webhooks

Update webhook

Delete webhook

Sample response

v2

v1

Delivery retries

Catch up on missed events

Before you start

List events

Parameters

Event fields

Page through the events

Data freshness and limits

Errors

Open In Colab

GitHub

​Example configurations to receive requests

​Create webhook

​Webhook v2 setup

​Webhook v1 setup

​Get webhooks

​Update webhook

​Delete webhook

​Sample response

​v2

​v1

​Delivery retries

​Catch up on missed events

​Before you start

​List events

​Parameters

​Event fields

​Page through the events

​Data freshness and limits

​Errors

Example configurations to receive requests

Create webhook

Webhook v2 setup

Webhook v1 setup

Get webhooks

Update webhook

Delete webhook

Sample response

v2

v1

Delivery retries

Catch up on missed events

Before you start

List events

Parameters

Event fields

Page through the events

Data freshness and limits

Errors