Configuring webhooks for datasets and projects

About datasets and projects webhooks

Dataset and project webhooks are designed to monitor key events within your data catalog. They allow real-time responses to changes in datasets, projects, insights, and files. Each event triggers a corresponding webhook that sends a notification to a specified URL. Webhooks can use an authorization key to verify the source of the events they receive. If the key does not match, the event will be ignored.

Dataset and project webhooks listen to events occurring within specific datasets or projects. You can configure webhooks for individual datasets and projects to track changes specific to those resources.

If you need to monitor all datasets and projects within your organization, consider using Organization webhooks instead, which provide broader coverage for all resources inside the organization.

Dataset and project webhooks handle data-related events, which are triggered by changes to datasets, projects, insights, and files. These events include creation, updates, and deletions. Each webhook payload contains details about the event, the affected resources, and the user who performed the action.

Webhook triggers for data events

Table 1.

Data type	Event
Datasets	Created, updated, or deleted Note: Сreate event is sent only if the dataset is public.
Projects	Created, updated, or deleted
Insights	Created, updated, or deleted
Files	Created, updated, or deleted

Webhook request for data events

The following table outlines the structure of the request body sent to your webhook URL when certain data-related events occur on data.world.

Table 1.

Field	Description
action	The type of event performed by the user (i.e., create, update, delete)
entity	The type of resource affected (i.e., dataset, project, file, insight)
actor	The user display name who performed the action
owner	The owner of the affected resource (i.e., user, organization)
dataset	The name of the dataset
project	The name of the project
insight	The name of the insight
file	The name of the file
timestamp	Date and time of the event
origin	System through which the action was performed (for example, prod-user-client, datadotworld-autosync)
links	Web and API URLs for affected resources

Example JSON Payload for data events

Data event webhook payload example

{
  "action": "update",
  "entity": "dataset",
  "origin": "prod-user-client",
  "links": {
    "api": {
      "dataset": "https://api.data.world/v0/datasets/8bank/dataset-of-books"
    },
    "web": {
      "actor": "https://data.world/sample-user-username",
      "owner": "https://data.world/sample-organization",
      "dataset": "https://data.world/8bank/dataset-of-books"
    }
  },
  "actor": "John Doe",
  "owner": "sample-organization",
  "dataset": "dataset-of-books",
  "dataset_version": "78b51e26-2",
  "timestamp": "2024-10-04T11:50:44.728115938Z",
  "previous_version_id": "07d935fe-1",
  "subscriberid": "agent:username"
}