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.

We split our information on webhooks into two articles:

If you manage Kordiam for your organisation but don't write code, please check this page: Setting up the webhook connection (What you need to do to get this running - no technical background required.)
Developer Reference: The full technical specification for the team configuring the receiving system.
(If you're building or maintaining the system that receives data from Kordiam, the following info is for you.)

Developer Reference

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

Authentication methods

Kordiam supports five authentication methods – for details, please see Setting up the Webhook Connection

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`