Webhooks
How to use Aquarium webhooks to communicate with your own services, including automating labeling service integrations.
Overview
This page provides two guides:
Integrating with Webhooks (Generically)
Integrating with Labeling Using Webhooks
Integrating With Webhooks
As a data operations platform, we encourage you to integrate with your other systems and tooling in your practice with Aquarium. To support use cases where you'd prefer for these events to be pushed to you via an HTTP request, we've implemented webhooks.
These webhooks can be triggered from these events:
dataset-complete
dataset-failed
issues-created
issue-update
issue-exported
It is up to you to provide an endpoint that the webhooks can communicate with. The webhook will send a POST request with a standard payload. The payload schemas can be seen here.
Configuration
Webhooks are configured for events per project, and can be edited under the Webhooks tab on a project page:

One endpoint can service multiple events, or you can configure a unique endpoint for every event you want to be alerted on. You can also deactivate the entire webhook if you need to quickly disable sending to it.
Testing the Webhook
You can also test the endpoint by sending a minimal test payload using the send icon; we will generate a test event and send it through the same processing pipelines that other events go through.

Payloads will always be POSTed to the endpoint, with the headers Content-Type: application/json
An authenticating header will also be included if one has been configured for the organization (see below).
Specific schemas can be viewed here, but all payloads will follow the same basic schema:
Authentication
When you configure a webhook that will be called by an Aquarium service, it will also be available for the public to call. To ensure that any payload you receive on that endpoint originated with Aquarium, we've provided a method to generate a secret key in your organization settings page. This key applies across all configured webhooks in all projects in your organization. We'll generate and show it only once in the UI, so please remember to write it down!
Once a secret key is generated, it will be set in all request headers as X-Aquarium-Secret which you can verify against the secret key you've been shown.

A new secret key will immediately replace the previous one.
Event Schemas
All event payloads will follow the same basic schema:
Below is an exhaustive list of schema definitions for every event that Aquarium supports and the shape of the [entity] in the payload.
Dataset Completed Processing
The dataset-complete event fires when a labeled dataset or an inference set for a labeled dataset has been uploaded; the shape will differ slightly depending on what was uploaded.
Dataset Failed Processing
The dataset-failed event fires when a labeled dataset or an inference set for a labeled dataset has been uploaded; the shape will differ slightly depending on what was uploaded.
Issues Related Events
Integrating with Labeling Using Webhooks
Motivation
A common use case for Aquarium datasets is to identify problem labels and group them using segments, downloading a JSON or CSV representation of a segment's elements, and then using scripting or a manual process to reformat the data to submit to a labeling service, whether an external vendor or an internal tool. By leveraging webhook configurations, the reformatting and submitting steps can be automated by a single handler. This allows an Aquarium user to directly send data to a labeling service directly from the UI without writing code each time.
The issue-exported event will POST the issue's elements to a webhook. A full schema can be found here:
Shaping the Webhook Payload To Send to Labeling
You can then use the elements in segment to create a new payload that is accepted by a labeling service; we've provided some sample code that serves a webhook endpoint and transforms an Aquarium payload to some common formats.
Triggering a Segment Export
To trigger an export, click the Export To Labeling button on an issue's page. If there aren't any webhooks configured to handle the issue-exported event on the issue's project, it will prompt you to create one.


If the payload was sent to the webhook successfully the modal will close. If not, an error will display in the modal window.
Last updated
Was this helpful?