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, deletions, and dataset sync failures or recoveries. Each webhook payload contains details about the event, the affected resources, and the user or system that 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. Sync failure or recovery notification Note: Triggered when a dataset fails to sync or successfully recovers. Includes error details on failure and file information on recovery.
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 and sync events occur on data.world.

Table 1. Webhook request for dataset data events

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

Table 2. Webhook request for dataset sync events

Field	Description
datasetid	The name of the dataset where the sync event occurred.
eventType	The type of sync event (syncTask.status.failure or syncTask.status.success). Note: syncTask.status.failure is triggered on the first failure for that file.
event.type	Status of the task (FAILURE or SUCCESS).
event.task	The name of the file or task that was syncing.
event.created	Timestamp when the event was triggered.
event.error	(Failure only) Error message received during the failed sync.
resourceUrl	URL to the file or resource related to the sync task.
resourceOwner	Owner of the dataset (user or organization).
resourceType	Type of the synced resource.

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"
}

Data sync webhook payload example

{
  "datasetid": "sync-demo",
  "event": {
    "type": "FAILURE",
    "task": "state_table.csv",
    "created": "2021-02-04T06:35:17.945Z",
    "error": "HTTP/1.1 404 Not Found"
  },
  "eventType": "syncTask.status.failure",
  "resourceUrl": "https://data.world/texas-whiskey/sync-demo/file/state_table.csv",
  "resourceType": "URL",
  "resourceOwner": "texas-whiskey"
}