How Can I use the Webhook-Based API

This document describes the functionality of the Webhook based integration that allows integration partners to get a notifications on a per-article-basis from the Scope System.

Fundamentals

A successful integration requires the integration partner to provide a endpoint that accepts HTTP POST requests with the data structure described below.

This endpoint can be either a system that is developed or maintained by the partner or alternatively can be any 3rd party system that supports integrations via Webhooks, for instance:

Whenever a end-user triggers a Webhook call in Scope, the Scope backend will immediately make an attempt to call this Webhook. One call always corresponds to exactly one article, or “Asset” in Scope.

Data Structure

The following JSON structure is sent to the receiving Webhook:

{
    "articleImageUrl": "https://storage.googleapis.com/scope-test-private-article-images/5312",
    "articleImageAltText": "Male subject on the phone",
    "articleTitle": "Nicht bei Netflix: Neuer Streamingdienst zeigt vergessenen Hit von Paul Walker",
    "articleSource": "TV Spielfilm Online",
    "articleComment": "Very cool stuff!",
    "articleUrl": "https://www.tvspielfilm.de/news/filme/konkurrenz-fuer-netflix-prime-amp-co-neuer-streamingdienst-filmtastatic-startet,10178263,ApplicationArticle.html",
    "articlePublicationDate": "2020-07-01T13:10:31Z",
    "tags": [
      {
        "id": 282,
        "title": "netflix"
      }
    ],
    "categories": [],
    "projects": [
      {
        "id": 73,
        "title": "A new Project"
      },
      {
        "id": 50,
        "title": "Another Project"
      }
    ]
  }

Field	Details

Field	Details
articleImageUrl	Please see How Can I use the Publication-Based API? \| Image Proxy (CloudImage) to learn more about image proxies to ensure perfectly cropped images.
articleImageAltText
articleTitle
articleSource
articleComment
articleUrl
articlePublicationDate	This is the initial publication date of the article. This date has been determined by the Scope system (by Diffbot, see below) and might’ve been adapted by the user. It is not related to the date of the webhook call. If you have a “record created” date in your receiving system, you will probably want to use the current date for that and add an extra field for this value.
tags	one or multiple tags, sent as an array
categories	one or multiple categories (can be predefined in the Scope settings by the user), sent as an array
projects	one or multiple projects (can be predefined in the Scope settings by the user), sent as an array

Data Source

Most structured article data in Scope, as shown above, is sourced via the external service Diffbot. However, most field values can be manually edited or added by users within Scope.

Please note that caching may occur on multiple levels, which can result in outdated values being displayed. If you notice incorrect data displayed by Diffbot or Scope, the root cause often lies in the CMS hosting the article. This can be due to:

• technical reasons (e.g., the CMS does not use standard metadata fields)
• editorial reasons (e.g., the article title was changed after publication)

If you notice systematic inconsistencies, please feel free to contact our support team.

You can try Diffbot’s extraction yourself on their website via Test Drive Extract.
Make sure to switch the extraction type from the default “Analyze” to “Article” before running the test.

Diffbot page: Test Drive Extract

Integration into receiving site

Please provide the URL as well as the credentials (if applicable, HTTP Basic Auth), and we will configure your Scope workspace accordingly.

Implementation Details

A Scope user may call the webhook repeatedly; the system won’t check for that.
Our system will make 3 attempts to deliver the message to the endpoint. After these 3 attempts, the call is dropped.
Scope recommends that the webhook is protected by HTTP Basic Auth and only available via HTTPS.