Get in touch
Get in touch

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 account management:

2) Click on the Create New Webhook button and select event options you need to trigger your hook:

3) Choose the event type and optionally constrain it to a Dataset.

4) Add the URL of an endpoint the webhook will request when the event is fired. 

If you need to pass authentication credentials or an API key to your endpoint, you can add this via the request header options. 

Add additional endpoints with the Add New button.

5) When you have configured your hook, click Create and the hook will be ready.

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

 

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