Skip to main content

Configuring webhooks for organizations

About organization webhooks

Organization webhooks are designed to monitor key events within your organization. They allow real-time responses to changes in datasets, projects, insights, and files, as well as monitoring access requests to them. 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.

Organization webhooks monitor events across all datasets and projects within your organization, without the need to configure separate webhooks for each resource. If you want to track a specific dataset or project, you can configure Dataset and project webhooks for more targeted event monitoring.

For example, you can use the organization webhooks in the following cases:

  • When a user requests access to a dataset, the webhook is triggered, notifying the system of this event.

  • When a new insight is created or an existing one is updated, the webhook also sends a notification.

When you set up an organization-level webhook, it monitors and sends notifications for events. Each webhook payload contains details about the event, the affected resources, and the user who performed the action.

Organization webhooks handle two distinct types of events:

  • Access events: Access events are triggered when a user requests access to a dataset or project, or when access is granted or revoked.

  • Data events: Data events are triggered by changes (create, update, delete) across all datasets, projects, insights, and files within the organization.

Webhook triggers for access events

Table 1.  

Event

Description

Access request

A user requests access to a dataset or project

Access granted

Access to a dataset or project has been granted

Access revoked

Access to a dataset or project has been removed



Webhook request for access events

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

Table 2.  

Field

Description

actorId

The username of the user triggered the event

actorName

The display name of the user triggered the event

granteeType

The type of entity being granted access

granteeEmail

The email address of the user being granted or requesting access

resourceName

The name of the dataset or project

resourceOwner

The resource owner ID of the dataset or project

resourceOwnerName

The display name of the owner of the dataset or project

resourceUrl

The URL of the resource

resourceId

The ID of the resource

event.created

The timestamp when the event was created

eventType

The type of event (for example, dataset.authorization_request.created)

authorizationLevel

The level of access requested or granted (i.e., READ, WRITE, ADMIN, NONE)

requestFormFieldsMessage

The message provided by the user when requesting access

requestId

A unique identifier for this access request event



Example JSON Payload for access events

Access event webhook payload example

{
  "actorId": "sample-user-username",
  "actorName": "John Doe",
  "granteeType": "USER",
  "granteeEmail": "sample-user-email@gmail.com",
  "granteeId": "sample-user-username",
  "granteeName": "John Doe",
  "resourceId": "dataset-of-books",
  "resourceName": "Dataset of books",
  "resourceOwner": "sample-organization",
  "resourceOwnerName": "Sample organization name",
  "resourceUrl": "https://data.world/sample-organization/dataset-of-books",
  "event": {
    "triggeredBy": "sample-user-username",
    "created": "Fri, 04 Oct 2024 13:35:16 GMT"
  },
  "eventType": "dataset.authorization_request.created",
  "authorizationLevel": "READ",
  "resourceAccessUrl": "https://data.world/sample-organization/dataset-of-books/access",
  "requestFormFields": {
    "Full name": "John Doe",
    "Message": "I want to receive access request event in the webhook"
  },
  "requestId": "9aba2dfc-9403-4d20-b68b-bcd6c7ccb170"
}

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

Configuring webhooks for an organization

Note

You can configure only one webhook per organization.

To configure a webhook for organization:

  1. Go to the organization where you want to enable webhooks.

  2. Go to the Settings tab > Webhooks.

  3. On the Webhooks page, set the following:

    1. Description: Provide a brief description of the webhook.

    2. Webhook URL: Provide a Webhook URL where events will be sent.

    3. Include authorization key: (Optional) Provide an authorization key for enhanced security. This key will be included in the request, allowing the webhook to verify request is from a trusted source.

      Note

      The same authorization key must be configured on both the webhook and the server that receives the events.

  4. Click Add.

In this section: