Webhooks are automated requests that send a JSON payload with information about a Project or task to a specified URL at a designated point in your Project’s Workflow. For example, if a webhook is added to the Complete stage of a Project, then a JSON payload containing the Project and task ID is sent every time a task reaches the Complete stage.
Common use-cases for webhooks include:

​
Setting Up Webhooks

Webhooks can be set up when creating or editing a Workflow. This includes setting up a Workflow while creating a new annotation Project, creating a Workflow template, or editing the Workflow of an existing Project.
Webhooks can only be added to Annotate and Complete stages. Webhooks on Annotate stages trigger when tasks are submitted for review. Webhooks on Complete stages trigger when a task is completed.
  1. With the Workflow open, click the Workflow stage you want to create a webhook for. A pop-up for to configure the Workflow stage appears.
  2. In the pop-up, click the Edit symbol under the Webhook heading.
  3. Enter the URL you want the JSON payload to be sent to. Press Enter on your keyboard to confirm.
  1. Ensure you save your changes.

​
Webhook Event Payloads

​
Task Submitted Payload

All task submitted events, triggered on the Annotate stage, have the following fields:
KeyTypeDescription
uidstringUnique identifier of the event.
versionintegerMajor version number to indicate backwards incompatible versions.
sourcestringThe source of the payload. Is always “Encord”.
event_typestringThe event type. task_sumbitted_event is triggered on the Annotate stage.
event_created_timestampstringA string of the timestamp in the ISO 8601 format. For example 2022-04-13T14:35:11.791161+00:00.
payloadobjectAn object containing the Project and label information.
project_hashstringThe unique identifier for the Project.
data_hashesstringThe unique identifiers for the data unit.
label_hashesstringThe unique identifiers for the Label Row.
Example payload: 
{
  "uid": "687457ce-6489-4891-b7c8-544477d99e41",
  "version": 1,
  "source": "Encord",
  "event_type": "task_submitted_event",
  "event_created_timestamp": "2024-03-25T15:18:55.406529+00:00",
  "payload": {
    "project_hash": "751a3a3e-46b6-4aad-b0b8-19b169f91266",
    "data_hashes": [
      "f0b012de-5aea-4457-b515-936b0c185771"
    ],
    "label_hashes": [
      "fdb9a21f-d9a7-48b5-9dac-dfe3e0e2c57f"
    ]
  }
}

​
Task Completed Payload

All task submitted events, triggered on the Complete stage, have the following fields:
KeyTypeDescription
uidstringUnique identifier of the event.
versionintegerMajor version number to indicate backwards incompatible versions.
sourcestringThe source of the payload. Is always “Encord”.
event_typestringThe event type. task_sumbitted_event is triggered on the Annotate stage.
event_created_timestampstringA string of the timestamp in the ISO 8601 format. For example 2022-04-13T14:35:11.791161+00:00.
payloadobjectAn object containing the Project and label information.
label_hashstringThe unique identifier for the Label Row.
project_hashstringThe unique identifier for the Project.
data_hashstringThe unique identifier for the data unit.
Example payload: 
{
  "uid": "950f9048-bd28-42e7-89cb-2538f27c1695",
  "version": 1,
  "source": "Encord",
  "event_type": "task_completed_event",
  "event_created_timestamp": "2024-03-25T15:13:40.456441+00:00",
  "payload": {
    "label_hash": "c25be5c7-2a7f-4de9-8afd-9e2f72064e84",
    "project_hash": "751a3a3e-46b6-4aad-b0b8-19b169f91266",
    "data_hash": "f5fb9c39-cbfc-4bf3-8fdb-95ee4da24c14"
  }
}

​
Webhooks for Manual QA Projects

Legacy notifications are now deprecated. We strongly advise using Workflow Projects.
Use the Notifications tab in Settings to manage push notifications and webhooks for Manual QA Projects. Filter and manage notifications using the:
  • + Create notification button: Initiates the notification creation flow.
  • Search bar: Typing in the search bar will filter the notifications by title.
  • List of notifications: Click the gear button to change a notification’s settings and click the red bin button to delete a notification.
You can create a number of event-based or timing-based notifications to help monitor your Project’s activity:
  • Email: send an email when certain events happen.
  • Slack: send a Slack message when certain events happen.
  • Digest: send regular emails giving a summary of activity over a given time period.
  • Webhook: send a JSON payload to a REST endpoint when certain events happen.
Creating notifications: To create a new notification, click the + Create notification button in the Notifications view. This initiates the notification creation flow, a simple step-by-step process for creating push notifications. 1. Enter details In the ‘Enter details’ screen, enter a notification title and optional description. A clear title and description helps keep your notifications organized and helps collaborators find what they are looking for. When you are happy, click Next. 2. Add Projects In the ‘Add projects’ screen, select the Projects you want to include in this notification. Click *Next to continue. 3. Add channels In the ‘Add channels’ screen, choose how you would like to receive the notification. Slack channels Click the Add Slack channel button to add a Slack channel. Once redirected to the Slack web page, make sure to first select the correct workspace from the top right drop-down list. Then select the channel you would like to post Slack notifications to. Add the channel and make sure to refresh the grid by clicking on the refresh icon above the Slack channels grid.
For a given user the available Slack channels are shared between all notifications. Email addresses Enter the email addresses of everyone who should receive the notifications in the entry box. A list of emails will appear above the box for each entered email.
Encord attempts to reduce the number of outgoing emails. New emails are not sent immediately, instead the email notifications are aggregated and sent in 5 minute intervals. This means, you may not receive emails immediately when an event triggers.
Webhooks Add a webhook by clicking the Add webhook button. Fill in all the relevant information.
You can create, change, and delete webhooks. You cannot attach or detach webhooks. To “detach” a webhook you need to delete it. Webhooks CANNOT be shared between notifications. Click here for a list of all possible events. Add triggers In the ‘Add triggers’ screen, choose what type of events trigger a notification. A notification can have multiple triggers. You can choose from ‘Reactive events’ and ‘Digest events’:
  • Reactive events: notification trigger in reaction to an event
  • Digest events: notification trigger at a scheduled times of day
Use the info icon next to the event type to get more detailed explanations on when these events are triggered. Create the notification Click Create to create the push notification.

​
IP Addresses for Webhooks

For teams with advanced security practices, you must add our IP addresses to an approved list to ensure that only trusted traffic from our services can access your webhook endpoints.
US Deployment refers to customers working on Encord’s US-hosted instance, rather than simply being located in the United States.
  • 34.89.106.119/32
  • 34.142.51.70/32