Organization webhooks

Overview

Organization webhooks empower downstream products to automatically record and respond to changes regarding access to datasets/projects within an organization. This enables a more efficient, reactive, and automated workflow in managing dataset access.

Understanding Organization Webhooks

When you set up an organization webhook in the Settings tab of your organization, it activates notifications for specific events related to dataset/project access. These events include when:

A request for access to a dataset/project is made
Access is granted to a dataset/project
Access is removed from a dataset/project

How Webhooks work

A webhook triggers a POST request to the URL you specify in your organization's settings. The payload of this request typically contains important details like:

Field	Description
`eventType`	Will be "dataset.authorization.created", "dataset.authorization.deleted", "dataset.authorization_request.created".
`granteeEmail`	The email of the user who is requesting or being granted access.
`granteeId`	The data.world ID of the user who is requesting or being granted access.
`granteeType`	Either "USER" for an individual user, or "ORGANIZATION" if an entire organization is granted access.
`resourceOwner`	The data.world ID of the owner of the dataset. This should match your org ID that you configured the webhook on.
`resourceId`	The data.world ID of the resource. When combined with `resourceOwner`, you can construct a URL to the resource, for example: `https://data.world/{resourceOwner}/{resourceId}`.
`authorizationLevel`	The access level, either NONE, READ, WRITE, or ADMIN.
`requestFormFields`	A customized key-value set of customizable form fields a user fills out when requesting access.
`event`	Metadata about the event, such as timestamp and the data.world ID of the user that triggered the event.

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

Example JSON Payload

{
  "eventType": "dataset.authorization_request.created",
  "granteeEmail": "[email protected]",
  "granteeId": "test-user",
  "granteeType": "USER",
  "resourceOwner": "my-test-org",
  "resourceId": "sample-test-dataset",
  "authorizationLevel": "READ",
  "event": {
    "triggeredBy": "test-user",
    "created": "Thu, 20 Sep 2019 19:10:45 GMT"
  },
  "requestFormFields": {
    "Full name": "test-user",
    "Contact email": "[email protected]",
    "Message": "This is a message test-user typed when requesting access"
  }
}

How to Enable Organization Webhooks

To enable organization webhooks:

Go to the organization where you want to enable webhooks.
On the Organization profile page, select the Settings tab > Webhooks section.

webhooks-settings

In the Webhooks configuration window, provide the Webhook URL and a brief description. Select Submit. The webhook has been configured.