Skip to content
Arc XP

Event Basics

IFX is an event-based application. Integrations are hosted code, meant to receive events and apply custom logic to the data passed from the emitting application.

Integrations remain at rest until receiving an event from another application (i.e. Composer, WebSked) to which it is subscribed (more on this later). If no integrations are subscribe to that event, the event is skipped.

Event Types

IFX has two types of events: synchronous and asynchronous

Asynchronous Events

These events do not affect user experience because the process is “fire and forget”. The application that emitted the event is not expecing a response from your integation.

Synchronous Events

These events can affect user experience because the emitting application is waiting on a response from your integration. For example, if a user is submitting a payment which is being processed through your integation, they will have to wait until the process is complete and a response is returned to the emitting application.

Event Namespace

Events will be in the format [app name]:[event name] e.g. websked:pitch_create

Event Payload

For all events, the contract is as follows:

{
  "key": "story:update", // event name
  "version": 2,
  "time": 1749134558, // timestamp
  "uuid": "",
  "body": {} // This JSON object is structured by the emitting application.
}

ANS requirements for triggering story:update

When sending ANS payloads directly into Arc APIs — which is commonly done during content migrations or when importing wire stories — and expecting IFX to trigger a story:update event, the message must meet specific criteria. If any of the required fields are missing or set incorrectly, the event will not fire.

Required ANS fields

The following values must be present in the ANS message to trigger story:update:

type: content-operation
operation: insert-story
created: false
published: true
body.additional_properties.is_published: true
body.additional_properties.publish_date must be present and not empty

These fields indicate that the story is considered published content and eligible for update events.

Preventing infinite event loops

If your integration is subscribed to story:update and also sends updates for that same story back to the Draft API, you can accidentally create an infinite loop. The update triggers story:update, your integration reacts, sends another update, and the cycle repeats.

To prevent this, any updates your integration sends back to Arc APIs must include the Arc-Priority: ingestion HTTP header. This ensures the message is ignored when it comes back through IFX.

Example:

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

In the next few articles we will explore content events, subscribing to events, custom events, and more.


Have a feature request or suggestion? Let us know on Our Ideas Portal.