Content Events

The Content API generates a real-time stream of data as changes arrive. This stream reflects changes to both published and unpublished content, and the data from the stream can be used to synchronize an external CMS with Arc XP, to extract the current state of certain content within Arc XP as it changes, or to perform limited real-time analytics on publishing changes.

As an IFX customer you automatically receive access to these content events! Once you are subscribed to an event, your integration will be invoked when the event is received.

IFX API Specs →

Content Events

Content events are available for stories, images, galleries and more. You can view the list on the Event Menu.

Caution

AVOID AN INFINITE LOOP!

Messages with a priority of ingestion are not supported, which is commonly used for content migrations or bulk-updating content.

If you are subscribed to story:update and send updates for that story from your integation back to Draft API, this will re-send story:update creating an infinite loop.

To avoid this it is crucial to include an HTTP header Arc-Priority: ingestion so that it will be ignored when it is coming back around.

const headers = {
  'Authorization': `Bearer ${arcPat}`,
  'Arc-Priority': 'ingestion'
};

Testing Content Events on Local Machine

You can simulate content events on your local machine. Creating Handlers to Receive Events with IFX will guide you through this process.

See also Locally Simulate HTTP Requests

Testing Content Events in Sandbox/Production

On sandbox and production, content events are triggered by user action rather than simulated. In this example we’ll use the story:update event.

Tip

Add verbose (non-sensitive) logs to your integation so that you can test event data, any data that is changed, successes of API requests, etc.

Prerequsites

Your integation is:

1. Promoted to live in the environment in which you are testing

2. Subscribed to story:update

Steps to Trigger story:update

1. Go into Composer and click “Update” on an existing story, or create a new one for your testing

2. Check your integration logs to make sure you are receiving an event like below, along with any other logs you added to your code:

Incoming JSON Event:
{
    "organizationId": "myorg",
    "currentUserId": "",
    "key": "story:update",
    "typeId": 1,
    "body": {
        "date": "2022-07-20T17:34:48.467Z",
        "_website_urls": [
            "/2022/07/20/my-story-2-update-1/"
        ],
        "source": {
            "system": "composer",
            "name": "myorg",
            "source_type": "staff"
        },
        "distributor": {
            "name": "myorg",
            "category": "staff",
            "subcategory": ""
        },
        "canonical_website": "my-site",
        "revision": {
            "editions": [
                "default"
            ],
            "user_id": "someone@washpost.com",
            "parent_id": "AAA6IEJ7Y5B2FP6GP6AVJMUNYY",
            "published": false,
            "branch": "default",
            "revision_id": "AAVFCJL2RCTTIUVX6A774YARQ"
        },
        "display_date": "2022-07-20T16:56:32.826Z",
        "headlines": {
            "tablet": "",
            "print": "",
            "meta_title": "",
            "native": "",
            "web": "",
            "mobile": "",
            "basic": "My story 2 - update-1"
        },
        "first_publish_date": "2022-07-20T16:47:23.147Z",
        "websites": {
            "my-site": {
                "website_url": "/2022/07/20/my-story-2-update-1/",
                "website_section": {
                    "referent": {
                        "website": "my-site",
                        "id": "/",
                        "type": "section"
                    },
                    "type": "reference"
                }
            }
        },
        "id": "AAAUC25RKRAKFGDROMTQ6QDPQY",
        "created_date": "2022-07-20T16:44:39.575Z",
        "last_updated_date": "2022-07-20T17:34:47.367Z",
        "_website_ids": [
            "my-site"
        ]
    },
    "version": 2,
    "uuid": ""
}

FAQ

What can be done with Content Events?

• Query for more ANS if needed
• Send data to an external system
• Use AI to enrich story tags
• Notify teams of changes to content

What cannot be done with Content Events?

• Change the structure of the messages which are sent
• Change the logic which determines event messages

Gallery Events

We’ve heard that the gallery events can be confusing, so here is some guidance that might help out.

In developer lingo…

gallery:create

if (!publish_date) {
  this is a gallery being saved for the first time
}

if (publish_date && publish_date === first_publish_date) {
  this gallery:
    was never saved
    is being published for the first time
}

gallery:publish

if (publish_date && publish_date === first_publish_date) {
  this gallery:
    was previously saved
    is being published for the first time
}

if (publish_date && publish_date !== first_publish_date) {
  this is an existing gallery being updated
}

Other things to know

1. An unpublished gallery will never have a publish_date
2. A gallery that has been published at any point in time will have first_publish_date
3. first_publish_date will never change values, and will still be present if the gallery is unpublished and/or republished