Request examples

The following examples detail the various JSON objects used with the webhooks endpoint.

Webhook edit

Data used to create or update a webhook.

Name

Type

Purpose

Label

String

A human-readable label describing the purpose of the webhook.

Uri

URI

The URI to make the web request to.

Method

String

The HTTP method to use when making the web request. Must be GET or POST.

Headers

Object

Custom headers to send when making the web request. Commonly used for authentication. The Header can only contain string properties.

Body

String

The body to post when making the web request. May only be populated if ExecutionMode is OnEnd.

BodyInclude

String

JSON object to include in the body of the webhook request. May only be populated if ExecutionMode is OnUpdate. This field must be a valid JSON object.

CreatedBy

String

The name of the user who created the webhook.

ExecutionMode

String

Determines how the webhook is executed. Must be OnEnd or OnUpdate.

Example:

RequestResponse

{
  "label": "webhook 29",
  "uri": "https://www.target-domain-of-the-webhook.com/hooks/edge-hook",
  "method": "POST",
  "headers": {
    "x-header": "bar"
  },
  "body": "{\"rebuild\":\"true\"}",
  "createdBy": "anco",
  "executionMode": "OnEnd"
}

Webhook

The information that defines a webhook is structured as follows:

Name

Type

Purpose

Id

String

The identifier used to identify this webhook.

TenantId

String

The ID of the tenant this webhook belongs to.

Label

String

A human-readable label describing the purpose of the webhook.

Uri

URI

The URI to make the web request to.

Method

String

The HTTP method to use when making the web request. Must be GET or POST.

Headers

Object

Custom headers to send when making the web request. Commonly used for authentication. The Header can only contain string properties.

Body

String

The body to post when making the web request. May only be populated if ExecutionMode is OnEnd.

BodyInclude

String

JSON object to include in the body of the webhook request. May only be populated if ExecutionMode is OnUpdate. This field must be a valid JSON object.

CreatedBy

String

The name of the user who created the webhook.

Created

DateTimeOffset

The timestamp when the webhook was created.

ExecutionMode

String

Determines how the webhook is executed. Must be OnEnd or OnUpdate.

Example:

RequestResponse

{
  "id": "5678",
  "tenantId": "target-corp",
  "label": "webhook 29",
  "uri": "https://www.target-domain-of-the-webhook.com/hooks/edge-hook",
  "method": "POST",
  "headers": {
    "x-header": "bar"
  },
  "body": "{\"rebuild\":\"true\"}",
  "createdBy": "anco",
  "created": "2021-03-26T10:44:04.6107312+00:00",
  "executionMode": "OnEnd"
}

Entity update

The entity update describes the updated entity that caused the webhook execution.

Name

Type

Description

identifier

String

The identifier of the entity.

entity_definition

String

The entity definition which the entity uses. Only populated for an update operation.

operation

String

The operation performed on the entity. Must be update or delete.

Example:

RequestResponse

{
  "identifier": "M.Setting.CleanerInterval",
  "entity_definition": "M.Setting",
  "operation": "update"
}

Webhook request

The body of a request made to a webhook endpoint that uses the OnUpdate execution mode.

Name

Type

Description

invocation_id

GUID

Identifies this invocation of the webhook. Used to correlate across large counts of updates spanning across multiple webhook requests.

updates

Array of EntityUpdate

The updated entities which caused the webhook execution.

continues

Boolean

Indicates whether there will be an additional request to continue sending more updates. This occurs when there are many updates and split between multiple requests.

If the webhook definition includes the bodyInclude field, this is inserted in the resulting JSON object.

Example:

RequestResponse

{
  "invocation_id": "7734f16b-1e46-4321-a40e-522255d6c17a",
  "updates": [
    {
      "identifier": "M.Setting.CleanerInterval",
      "entity_definition": "M.Setting",
      "operation": "update"
    },
    {
      "identifier": "Content.PowerFromWithin",
      "operation": "delete"
    }
  ],
  "continues": false
}

In the following example, the webhook definition includes the following for the bodyInclude field:

RequestResponse

{
  "authorization": 132332,
  "rebuild": true,
  "department": "engineering"
}

All properties of the JSON object are added to the JSON request body:

RequestResponse

{
  "authorization": 132332,
  "rebuild": true,
  "department": "engineering",
  "invocation_id": "7734f16b-1e46-4321-a40e-522255d6c17a",
  "updates": [
    {
      "identifier": "M.Setting.CleanerInterval",
      "operation": "delete"
    },
    {
      "identifier": "Content.PowerFromWithin",
      "entity_definition": "M.Content",
      "operation": "update"
    }
  ],
  "continues": false
}

OnUpdate execution

If there are many updates to send, these are split into batches and sent over multiple requests. All requests for the same invocation (triggers) have the same invocation_id set. All requests have the continues field set to true except the last request for the invocation. Downstream systems can use this field to know whether to expect additional requests for the invocation or not.

Example:

Consider an update of three separate entities. If the maximum batch size is 2, then the payloads of the requests sent to the webhook endpoint are as follows:

RequestResponse

{
  "invocation_id": "8834f16b-1e46-4321-a40e-522255d6c17a",
  "updates": [
    {
      "identifier": "M.Setting.CleanerInterval",
      "entity_definition": "M.Setting",
      "operation": "update"
    },
    {
      "identifier": "Content.PowerFromWithin",
      "entity_definition": "M.Content",
      "operation": "update"
    }
  ],
  "continues": true
}

The continues field is true, indicating that another request follows:

RequestResponse

{
  "invocation_id": "8834f16b-1e46-4321-a40e-522255d6c17a",
  "updates": [
    {
      "identifier": "M.Setting.UpdateInterval",
      "entity_definition": "M.Setting",
      "operation": "update"
    }
  ],
  "continues": false
}

Do you have some feedback for us?

If you have suggestions for improving this article,