Get in touch
Get in touch

Webhooks

Webhooks are an integration mechanism that allow you to trigger actions in some downstream business system or application, when certain events occur in Data Graphs, such as creating or updating a Concept. 

When one of these webhook-enabled events occur, Data Graphs invokes a web service in some external environment that you have configured. This lets you react to changes in Data Graphs without having to poll the API. They are essentially a push integration.

You can create a webhook based on a combination of one or more of the following criteria:

  • Event type - was a Concept created, updated, merged, or deleted, or was a candidate Concept accepted
  • Dataset - an event constrained to a specific Dataset
  • Concept type - an event constrained to a specific Concept type

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 the event options you need to trigger your hook:

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

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

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

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

Webhook request sample payloads

ConceptCreated

{ 
  "conceptType": "urn:demo:types:Country", 
  "eventType": "ConceptCreated", 
  "eventTarget": "urn:demo:Country:49GRFtuRHe2aaQNRc8ferw", 
  "eventDate": "2020-11-19T10:32:33.518Z", 
  "concept": { 
    "fullName": "French Republic", 
    "long": 2.3522,
    "countryCode3": "fra", 
    "countryCode": "fr", 
    "name": "France", 
    "id": "urn:demo:Country:49GRFtuRHe2aaQNRc8ferw", 
    "lat": 48.8566
  }
}

ConceptUpdated

{
  "conceptType": "urn:demo:types:Country", 
  "eventType": "ConceptUpdated", 
  "eventTarget": "urn:demo:Country:49GRFtuRHe2aaQNRc8ferw", 
  "eventDate": "2020-11-19T10:32:33.518Z", 
  "originalConcept": { 
    "fullName": "French Republic", 
    "long": 2.3522,
    "countryCode3": "fra", 
    "countryCode": "fr", 
    "name": "France", 
    "id": "urn:demo:Country:49GRFtuRHe2aaQNRc8ferw", 
    "lat": 48.8566                  
   }, 
  "modifiedConcept": { 
    "fullName": "French Republic", 
    "long": 2.48, 
    "countryCode3": "fra", 
    "countryCode": "fr", 
    "name": "France", 
    "id": "urn:demo:Country:49GRFtuRHe2aaQNRc8ferw", 
    "lat": 48.8566
  }, 
  "propertiesModified": ["long"]
}

ConceptDeleted

{ 
  "conceptType": "urn:demo:types:Country", 
  "eventType": "ConceptDeleted", 
  "eventTarget": "urn:demo:Country:49GRFtuRHe2aaQNRc8ferw", 
  "eventDate": "2020-11-19T10:32:33.518Z"
}

ConceptMerged

{
  "conceptType": "urn:demo:types:Country", 
  "eventType": "ConceptMerged", 
  "eventTarget": "urn:demo:Country:49GRFtuRHe2aaQNRc8ferw", 
  "eventDate": "2020-11-19T10:32:33.518Z", 
  "sourceIds": [
    "urn:demo:Country:DFrfds32uu33ldsadjkFSKkA", 
    "urn:demo:Country:876hasdASDasdi8"
  ], 
  "concept":  { 
    "fullName": "French Republic", 
    "long": 2.48, 
    "countryCode3": "fra", 
    "countryCode": "fr", 
    "name": "France", 
    "id": "urn:demo:Country:49GRFtuRHe2aaQNRc8ferw", 
    "lat": 48.8566
  }
}