Introduction

Webhooks are HTTP ‘callback’ functions designed to remove the inefficiency of the client polling the server across the wide area network to check for server-side changes. Webhooks are placed on the server side so updates to the source content automatically trigger an API call to all clients that have requested webhooks for that content. The client then uses the payload and headers to trigger bespoke updates to their use of that content.

Webhooks setup and use

Webhooks are set up by Cortex on the server side. If webhooks are required, please contact your Cortex account manager to request the service, and provide:

• The URL (endpoint) to which our server API call should be made;
• The HTTP method to use (which will otherwise default to POST);
• Any additional HTTP headers for use in, for example, validating the integrity of the interaction through passing an API key. The client can also request that we include bespoke headers for internal use on the client side.
• The topic - or ‘event type’ - that Cortex will use is also sent as a header X-CMS-Topic to the webhook URL where the Topic type is one of: CREATED, UPDATED, PUBLISHED, UNPUBLISHED, or DELETED.

It is important to note that the topic does not directly instigate change at the client side. It is up to the client to use the topic and header information to instigate appropriate actions; for example, if an article is deleted in Cortex it will be necessary to delete it from the cache on the client side.

Below is an example of a webhook for client ID DEMO using an article on stage and webhook.site - a webhook site where you can test and experiment with webhooks.

{
  "_id": "DEMO",
  "webhooks": [
    {
      "url": "https://webhook.site/b15507f1-e1c1-4491-96b1-6ee120348162",
      "method": "POST",
      "headers": {
        "X-Example-Additional-Header": "example"
      }
    }
  ]
}

And the JSON result at the remote client (i.e., at webhooks.site) looks like this:

{
  "id": "653ef42c-7edd-46cb-9597-4378f02bb53e",
  "content": [
    {
      "id": "873e0d41-999d-41fc-9b74-59e56aa58779",
      "contentType": "TEXT",
      "content": "New Block",
      "isHtml": false
    }
  ],
  "language": "en",
  "version": 6,
  "source": {
    "sourceSystem": "BRIDGE",
    "overwriteEnabled": false
  },
  "clientId": "DEMO",
  "heroMedia": {
    "content": {
      "id": "8b739997-eb45-47bf-b031-c670b0d7161a",
      "contentType": "IMAGE",
      "image": "https://media-cdn.incrowdsports.com/2f78008c-d1da-468e-8e28-c735dcf890aa.webp"
    },
    "title": "Test Webhook ",
    "summary": "This is a test"
  },
  "readTimeMinutes": 1,
  "auth": {
    "loginRequired": false,
    "roles": [],
    "entitlements": []
  },
  "pinned": false,
  "articleMetadata": {},
  "singlePage": false,
  "displayCategory": {
    "id": "ad013efe-140f-4aad-aa7d-1046cb12a1c2",
    "text": "Community"
  },
  "slug": "52e1e587-216a-42d7-8fe0-976cd76e1d5a",
  "linkedIds": [
    {
      "sourceSystem": "MEDIA",
      "sourceSystemId": "2f78008c-d1da-468e-8e28-c735dcf890aa"
    }
  ],
  "categories": [
    {
      "id": "ad013efe-140f-4aad-aa7d-1046cb12a1c2",
      "text": "Community"
    }
  ],
  "blocked": false
}

Also note that, whatever the topic or headers, the body of the payload will always be the entire article in its new current state.

If you would like to use webhooks in your service, in the first instance, please contact your Cortex account manager or administrator.