Webhooks

Webhooks

Webhooks are a resource that can be used to enabled complex workflows and real-time use cases.

Instead of polling the API for static data or consistently exporting labels, webhooks allow subscriptions to data when certain actions are performed – leading to notifications of these events. They can be configured to notify services you have set up, and can fit within a larger workflow in your model development. We’ll send a POST payload with the relevant information each time a webhook is triggered.

Webhooks can be enabled organization-wide or on specific projects you choose.

The terms we use for webhooks are webhooks, topics, and notifications.

Webhooks

A Webhook is the main interface for subscribing to events that occur within Labelbox. On creation, it takes in: * URL endpoint: the URL notifications are sent to * Topics: the list of events (below) notifications are sent for * Secret: a secret used to validate the request is coming from Labelbox (more information below) * Project: (optional) a specific project that the notifications should correspond to

Topics

Topics are the events that a webhook can be subscribed to. We currently support the following topics: - LABEL_CREATED, LABEL_UPDATED, LABEL_DELETED - REVIEW_CREATED, REVIEW_UPDATED

Notifications

Each time a webhook POST payload is sent, a Notification will be recorded to capture the request and response itself, along with all relevant metadata about the POST. It includes the request header, request body, response headers, response body, and response code. This enabled you to verify webhooks are successfully sending data and to debug any potential issues when setting up webhooks.

Security

In order to verify that notifications are coming from Labelbox and not elsewhere, we have the request header X-Hub-Signature. This header is created using the secret you provided when creating the webhook and the request body payload. A SHA-1 hash is created using the body and encrypted using the secret as the key. You can verify this is valid webhook notification by creating your own SHA-1 hash using the payload and secret, and validating it is the same as in the header.

Integration Walk Through

To develop a new integration using webhooks you can follow the below workflow.

# pip install flask
from flask import Flask, request
import json
app = Flask(__name__)

@app.route('/')
def hello_world():
return 'Hello, World!'

@app.route('/webhook-endpoint', methods=['POST'])
def print_webhook_info():
print('=========== New Webook Delivery ============')
print('Delivery ID: %s' % request.headers['X-Labelbox-Id'])
print('Signature: %s' % request.headers['X-Hub-Signature'])
print('Event: %s' % request.headers['X-Labelbox-Event'])
print('Payload: %s' % json.dumps(json.loads(request.data.decode('utf8')),indent=4))
return 'Success'

if __name__ == '__main__':
app.run(host='0.0.0.0', port=3000, debug=True)

When starting the above server, you should be able to visit http://0.0.0.0:3000 and see “Hello, World!”

However, Labelbox won’t be able to send messages to http://0.0.0.0:3000 because it’s on your local network. You can either deploy this server or use ngrok which is a great tool that will provide a public HTTP proxy to your local endpoint.

ngrok http 0.0.0.0:3000
# You'll recieve a public endpoint I.E. https://83a053ae.ngrok.io

Then use this ngrok URL in the below query…

Click here to explore query.

mutation CreateWebhook {
createWebhook(data:{
project:{
id:"<PROJECT_ID>"
},
url:"<HTTP_URL>",
secret:"<ANY_SECRET>",
topics:{set:[LABEL_CREATED, LABEL_UPDATED, LABEL_DELETED]}
# topics:{set:[REVIEW_CREATED, REVIEW_UPDATED, REVIEW_DELETED]}
}){
id
}
}

If you head to the project and create, update, or delete a label, a notification will be sent to the Python server you have created.

After verifying and when entering production, the following update query will change to the production URL.

mutation UpdateWebhook {
updateWebhook(where:{
id:"<WEBHOOK_ID>"
}, data:{
url:"<PRODUCTION_URL>",
}){
id
}
}


How did we do?