Global Export Integration (Webhooks) – Kordiam Support

The Global Export integration connects Kordiam to external systems – primarily a content management system (CMS) – by automatically sending story and event data whenever something changes. Think of it as a live feed: whenever a story is created, updated, or deleted in Kordiam, your CMS receives that information without anyone having to manually export or copy anything.

This article is split into two parts:

Part 1 – Admin Setup Guide: What you need to do to get this running. No technical background required.
Part 2 – Developer Reference: The full technical specification for the team configuring the receiving system.

If you're not sure which part applies to you:
If you manage Kordiam for your organisation but don't write code, Part 1 is for you.
If you're building or maintaining the system that receives data from Kordiam, go to Part 2.

Part 1 – Admin Setup Guide

What this integration does

When the Global Export is active, Kordiam automatically sends data to your CMS whenever a story or event is created, updated, or deleted. Your CMS receives that data and can use it to create or update content on your site – without any manual steps from your team.

You don't configure this yourself. You collect a few pieces of information and pass them to Kordiam's Customer Success team, who handles the setup on your behalf.

What you'll need before you contact us

Your IT contact or CMS provider can supply all of this:

1. Your CMS endpoint URL – the address Kordiam will send data to. It looks something like https://yourcms.com/api/content.
2. An authentication token – a key that proves to your CMS that the data is coming from Kordiam. Treat this like a password. When sharing it with us, we recommend using a one-time link service such as pwpush.com rather than sending it in plain email.
3. Your Kordiam account name – find this at kordiam.app/accountPage.htm when logged in as an admin. Alternatively, provide the email address of your account's admin.

Optional: trigger rules

By default, Kordiam sends data for stories at any status – Pitch, Accepted, and so on. If you want to exclude certain story statuses from triggering an export (for example, you only want to push stories that have been accepted), let us know when you get in touch and we'll configure that for you.

How to get started

Email support@kordiam.io with the information listed above. The Customer Success team will set up the connection and confirm when it's live. You don't need to take any further technical steps.

Things worth knowing

What happens if my CMS is unavailable?
If Kordiam can't reach your CMS, it will retry three times at five-second intervals. If all retries fail, that update is not re-sent automatically. If you know your CMS was down for a period, you can retrieve the latest version of any story via the Kordiam API, or contact support.

Can I have more than one webhook connection?
Yes. Kordiam supports multiple simultaneous webhook connections – for example, if you're sending data to more than one system.

What time zone is used for dates and times?
All data is sent in GMT (UTC+0).

What happens with cross-day publication slots?
If a publication time slot starts on one day and ends the next, Kordiam sends the publication date as the start day plus one.

Part 2 – Developer Reference

This section covers the technical specification for the system receiving data from Kordiam's Global Export integration.

Authentication methods

Kordiam supports five authentication methods. Confirm with the Kordiam team which method applies to your setup:

1. Bearer token (username/token) – URL + persistent token
2. AWS SQS (Simple Queue Service) – queue-based delivery
3. JWT (JSON Web Token) – URL + persistent token
4. Bearer token (API key/secret) – api_key + api_secret
5. Custom header – custom header key/value pair

Trigger conditions

Kordiam sends a request when all of the following are true:

The story/event is in a non-excluded status (excluded statuses are configured per account)
At least one of the following fields has changed:
- Story title or description
- Slug
- Story status
- Note
- Groups
- Custom fields
- Producer task (status, assignee, deadline, note, content, text length, custom fields)
- Publication (status, platform, category, publishing date/time, type, custom fields)

Endpoints

Kordiam uses "element" to refer to both stories and events.

Event	Method	Endpoint	Notes
Story/event created	POST	`{url}/element`	Response must include `{"id": 123}` — this becomes the external ID used for all subsequent requests
Story/event updated	PUT	`{url}/element/{id}`	`{id}` is the external ID returned at creation
Story/event deleted	DELETE	`{url}/element/{id}`	`{id}` is the external ID returned at creation

Important: The external ID returned in the POST response is how Kordiam links the story to your system. If Kordiam does not receive this ID, subsequent PUT and DELETE requests will be sent with a null ID. You can set or update this ID at any time via the Kordiam API.

Data payload

The following fields are included in POST and PUT request bodies:

id – Kordiam story ID
title – story title/description
slug
note
elementStatus – {id, name}
modificationDate – ISO 8601, UTC
groups – [{id, name, parent (optional), selected}]
externalElement – {id, link} – the external system's ID and link, stored in Kordiam
tasks – array: {id, format {id, name}, status {id, name}, confirmationStatus {id, name}, assignee {id, name/email, external_id}, deadline {date, time}, note, textLength {id, name, maxValue, type}, done}
publications – array: {id, status {id, name}, platform, category {id, name}, type {id, name}, single {start {date, time}, issue_label}, published {start {date}}, assignments, customFields, isMain}

For full field definitions, refer to the Kordiam API documentation. Note that the API specification contains additional fields beyond what the webhook payload includes. Contact support@kordiam.io to request additional fields in your export.

Request examples

POST – new story created

Endpoint: POST http://yourcms.example.com/element

Headers:

Accept: application/json, application/*+json
Content-Type: application/json;charset=UTF-8
Content-Length: {length}
Authorization: Bearer {token}

Body:

{
 "id": 123456,
 "tasks": [
   {
     "id": 121314,
     "format": { "id": 8, "name": "Text" },
     "status": { "id": 1, "name": "Requested" }
   }
 ],
 "publications": [
   {
     "id": 145678,
     "status": { "id": 1, "name": "No Status" },
     "platform": 99999,
     "single": { "start": { "date": "2021-03-10" } }
   }
 ],
 "elementStatus": { "id": 1, "name": "pitch" },
 "title": "TEST request",
 "groups": [{ "id": 20082, "name": "Team" }]
}

Expected response:

{ "id": 123 }

PUT – story updated

Endpoint: `PUT http://yourcms.example.com/element/123`