[Connectors] Webhook connector

The webhook connector forwards platform events in real time to external HTTPS endpoints, such as a Make scenario.

It is configured like the other connectors, from an integration: a JSON configuration declares the endpoints, configuration constants store URLs and secrets, and a mapping defines the forwarded concepts and fields when required.

Note: The webhook connector is available on demand. Please contact the CSM team to activate it.

Endpoint types

A single configuration can declare several endpoints. Each endpoint has one of two types:

Only some field types can be mapped (see Supported types). Updates on other fields, such as multidimensional fields, can only be received through a raw endpoint.

Configuration

The configuration is a JSON array of endpoints:

[
  {
    "id": "all-visible-updates",
    "type": "raw",
    "endpoint": "${url1}",
    "authenticationHeader": {
      "name": "x-make-apikey",
      "value": "${token1}"
    }
  },
  {
    "id": "code-catalog",
    "name": "Code catalog",
    "type": "mapped",
    "endpoint": "${url2}",
    "authenticationHeader": {
      "name": "x-make-apikey",
      "value": "${token2}"
    },
    "mappings": {
      "workspace": {
        "name": "0. Workspace",
        "fields": {
          "name": { "name": "Name", "type": "text" },
          "url": { "name": "Url", "type": "link" },
          "isPrivate": { "name": "Is private", "type": "boolean" },
          "repositories": { "name": "Repositories", "type": "embedding", "with": "repository" }
        }
      },
      "repository": {
        "name": "1. Repository",
        "fields": {
          "name": { "name": "Name", "type": "text" },
          "url": { "name": "Url", "type": "link" }
        }
      }
    }
  }
]

${...} values refer to configuration constants (see Connectors).

Important: Any invalid entry invalidates the whole configuration. No endpoint receives events until the configuration is fixed. Unknown properties are rejected.

Endpoint properties

Authentication header

The authentication header is optional but strongly recommended. Without it, the receiver accepts requests from anyone who knows the endpoint URL, which can lead to data leaks.

• The value should be stored in a secret constant, for example "value": "Bearer ${WEBHOOK_TOKEN}". A literal value is stored in clear text in the configuration.

• The header is only sent to its own endpoint. The integration token is never sent to endpoints.

• Transport headers, such as Content-Type or Host, cannot be used.

• A new constant value is only applied at the next configuration change.

Mappings

Each entry of mappings declares a concept. Its key is the concept alias.

Each entry of fields declares a field:

Webhook mappings are read-only: unlike other connectors, mode is not supported and invalidates the configuration.

Supported types

Fields are declared with name and type:

Associations are declared with name, type, and with:

with is the alias of the target concept, which must be declared in the mappings of the same endpoint:

"mappings": {
  "useCase": {
    "name": "Use case",
    "fields": {
      "name": { "name": "Name", "type": "text" },
      "domain": { "name": "Domain", "type": "n-1", "with": "domain" },
      "dataAssets": { "name": "Data assets", "type": "n-n", "with": "dataAsset" },
      "status": { "name": "Status", "type": "workflow", "with": "status" }
    }
  },
  "domain": {
    "name": "Domain",
    "fields": { "name": { "name": "Name", "type": "text" } }
  },
  "dataAsset": {
    "name": "Data asset",
    "fields": { "name": { "name": "Name", "type": "text" } }
  },
  "status": {
    "name": "Status",
    "fields": { "name": { "name": "Name", "type": "text" } }
  }
}

A reference to a concept of another endpoint, or to an undeclared alias, invalidates the configuration.

Aliases

Concept and field aliases are the names sent in the payload, instead of the Portfolio concept names, field names, or API aliases. In the example above, the Is private field is sent as "isPrivate": <value>.

Aliases therefore allow the payload to match the format expected by the receiver.

Mapping

A valid configuration with at least one mapped endpoint displays the Mapping tab of the integration. As for the other connectors, each declared concept and field must then be mapped to a Portfolio concept and field.

A mapped endpoint receives nothing until its mapping is done.

• Changing an endpoint name, URL, or authentication header keeps the existing mapping.

• Changing an endpoint id, a concept alias, or a field alias deletes the corresponding mapping, which must be done again.

Rights

Only data readable by the integration is forwarded. Read rights should be limited to the data the receivers are allowed to see.

Payloads

Each event is sent as a JSON POST request.

Raw endpoints

The SSE message is forwarded unchanged:

{
  "eventId": "1760350000000-0",
  "status": "validated",
  "origin": { "source": "CLIENT" },
  "event": [
    { "id": ["<object id>"], "properties": { "<property id>": "<value>" } },
    { "id": ["<deleted object id>"], "properties": null }
  ],
  "checksum": "<store checksum>",
  "permissionUpdated": false
}

Mapped endpoints

One request is sent per endpoint, containing only the instances mapped for that endpoint:

{
  "eventId": "1760350000000-0",
  "origin": { "source": "CLIENT" },
  "message": [
    {
      "id": "<instance id>",
      "type": "workspace",
      "multiple": false,
      "properties": { "name": "Platform team", "isPrivate": true }
    },
    {
      "id": "<instance id>",
      "type": "repository",
      "multiple": false,
      "properties": null
    }
  ]
}

• type: concept alias.

• properties: values keyed by field aliases, null for a deleted instance.

• multiple: true when the concept is mapped several times in the integration.