Webhooks

Webhooks are an integration mechanism that allow you to trigger actions in a downstream business system or application in response to certain Data Graphs events, such as creating or updating a Concept. This lets you react to changes in Data Graphs without having to poll the API. They are essentially a push integration.

Data Graphs webhooks to respond to the following event types:

• Concept Created
• Concept Updated
• Concept Merged
• Concept Migrated
• Concept Deleted
• Candidate Concept Accepted
• CSV Imported
• Dataset Deleted
• All Concepts in Dataset Deleted
• All Concepts for Type Deleted
• Multiple Concepts Deleted

Each can listen for changes in all Datasets or can be constrained to a specific Dataset.

When one of these events occurs, Data Graphs sends a POST request to your external environment with the event's details in the payload; examples of each type of payload are listed below. In fact, you can set up a webhook to make multiple POST requests by configuring multiple endpoints;

Creating a webhook

To create a webhook you must have the role Owner, Administrator or Developer. 

1) Navigate to the Webhooks screen in project management:

2) Click on the Add Webhook button and select an Event Type and Target Dataset, and add the Endpoint of the webhook that will be invoked.

In the following example, any Concept added to the Organizations Dataset will send details of that event to https://webhook-domain.com/endpoint:

You can add additional endpoints to each event and pass authentication credentials or an API key to each endpoint. 

3) When you have configured your hook, click Save and the hook will be ready.

4) Clicking the Test button on your new hook will enable you to trigger it manually using a sample payload and check that it is received correctly at the endpoints(s) you have provided.

Pre-Commit Endpoint

If you choose to target All Datasets there is an additional option to create a single Pre-Commit endpoint for a create, update, merge, migrate or delete Concept event.

This allows a consumer of the pre-commit hook to carry out an impact assessment on your data or the event before carrying out the action. It allows a downstream system to either cancel the change entirely, approve the change, or respond with an assessment or warning that the Data Graphs user can interpret.

Pre-Commit webhooks will handle three cases:

• No impact – the action is completed with no notification in the UI.
• Reject – a modal informs the user that the action cannot be completed.
• Warning – a modal informs the user that the action can be completed with details of the impact with a prompt to continue.

Webhook request sample payloads

ConceptCreated

{
  "type": "DataObjectEvent",
  "guid": "event-guid",
  "epoch": 1605781971,
  "targetDataset": {
    "name": "Concepts",
    "id": "urn:demo:concept"
  },
  "operation": "Created",
  "eventDate": "2020-11-19T10:32:33.518Z",
  "eventType": "DataObjectCreated",
  "eventTarget": "urn:demo:Concept:guid",
  "account": "demo",
  "sourceType": "User",
  "eventAgent": {
    "id": "urn:demo:user:guid",
    "name": "Demo User"
  },
  "objectVersion": {
    "label": "label1",
    "prop1": "value1",
    "prop2": "value2",
    "id": "urn:demo:Concept:guid",
    "type": "Concept"
  }
}

ConceptUpdated

{
  "type": "DataObjectEvent",
  "guid": "event-guid",
  "epoch": 1605781971,
  "targetDataset": {
    "name": "Concepts",
    "id": "urn:demo:concept"
  },
  "operation": "Modified",
  "eventDate": "2020-11-19T10:32:33.518Z",
  "eventType": "DataObjectUpdated",
  "eventTarget": "urn:demo:Concept:guid",
  "account": "demo",
  "sourceType": "User",
  "eventAgent": {
    "id": "urn:demo:user:guid",
    "name": "Demo User"
  },
  "objectVersion": {
    "label": "label1",
    "prop1": "value1",
    "prop2": "value2",
    "id": "urn:demo:Concept:guid",
    "type": "Concept"
  },
  "propertiesModified": [
    {
      "propertyName": "prop1",
      "newValue": "New value of prop1",
      "oldValue": "Old value of prop1"
    }
  ]
}

ConceptDeleted

{
  "type": "DataObjectEvent",
  "guid": "event-guid",
  "targetDataset": {
    "name": "Concepts",
    "id": "urn:demo:concept"
  },
  "operation": "Deleted",
  "eventDate": "2020-11-19T10:32:33.518Z",
  "eventType": "DataObjectDeleted",
  "eventTarget": "urn:demo:Concept:guid",
  "account": "demo",
  "sourceType": "User",
  "eventAgent": {
    "id": "urn:demo:user:guid",
    "name": "Demo User"
  },
  "objectVersion": {
    "label": "label1",
    "prop1": "value1",
    "prop2": "value2",
    "id": "urn:demo:Concept:guid",
    "type": "Concept"
  }
}

ConceptMerged

{
  "type": "DataObjectEvent",
  "guid": "event-guid",
  "epoch": 1605781971,
  "targetDataset": {
    "name": "Concepts",
    "id": "urn:demo:concept"
  },
  "operation": "Modified",
  "eventDate": "2020-11-19T10:32:33.518Z",
  "eventType": "DataObjectMerged",
  "eventTarget": "urn:demo:Concept:guid",
  "account": "demo",
  "sourceType": "User",
  "eventAgent": {
    "id": "urn:demo:user:guid",
    "name": "Demo User"
  },
  "objectVersion": {
    "label": "label1",
    "prop1": [
      "value1 updated",
      "value2 updated"
    ],
    "prop2": "value2",
    "id": "urn:demo:Concept:guid",
    "type": "Concept"
  },
  "propertiesModified": [
    {
      "propertyName": "prop1",
      "newValue": [
        "value1 updated",
        "value2 updated"
      ],
      "oldValue": [
        "old value of prop1",
        "old value of prop1"
      ]
    },
    {
      "propertyName": "prop1",
      "newValue": "2020-11-19T10:36:46.869Z",
      "oldValue": "2020-11-19T10:34:27.694Z"
    }
  ],
  "sourceIds": [
    "urn:demo:Concept:merged-concept-guid"
  ]
}

CandidateAccepted

{
  "type": "CandidateEvent",
  "guid": "event-guid",
  "epoch": 1605781971,
  "targetDataset": {
    "name": "Concepts",
    "id": "urn:demo:concept"
  },
  "operation": "Modified",
  "eventDate": "2020-11-19T10:32:33.518Z",
  "eventType": "CandidateAccepted",
  "eventTarget": "urn:demo:Concept:guid",
  "account": "demo",
  "sourceType": "User",
  "eventAgent": {
    "id": "urn:demo:user:guid",
    "name": "Demo User"
  },
  "objectVersion": {
    "label": "label1",
    "prop1": "value1",
    "prop2": "value2",
    "id": "urn:demo:Concept:guid",
    "type": "Concept"
  }
}

CSVImported

{
  "type": "CSVImport",
  "guid": "event-guid",
  "epoch": 1605781971,
  "targetDataset": {
    "name": "Concepts",
    "id": "urn:demo:concept"
  },
  "operation": "Created",
  "eventDate": "2020-11-19T10:32:33.518Z",
  "eventType": "CSVImported",
  "account": "demo",
  "sourceType": "User",
  "objectCount": 100,
  "eventAgent": {
    "id": "urn:demo:user:guid",
    "name": "Demo User"
  },
  "objectVersions": [
    {
      "label": "label1",
      "prop1": "value1",
      "prop2": "value2",
      "id": "urn:demo:Concept:guid",
      "type": "Concept"
    },
    {
      "label": "label1",
      "prop1": "value1",
      "prop2": "value2",
      "id": "urn:demo:Concept:guid2",
      "type": "Concept"
    },
    {
      "label": "label1",
      "prop1": "value1",
      "prop2": "value2",
      "id": "urn:demo:Concept:guid3",
      "type": "Concept"
    }
  ]
}