Inbound Events

Inbound events allow you to notify ChronosHub when something happens in your system. You send events by making an HTTP POST request to our API. Each request is authenticated with the API key you received during onboarding.

How It Works

1. You send a POST request to the inbound endpoint with your event payload.
2. ChronosHub authenticates your API key.
3. ChronosHub validates the payload against the JSON Schema agreed for that event type during onboarding.
4. On success you receive a 202 Accepted response with an event ID for your records.
5. ChronosHub processes the event asynchronously — no further action is needed from your side.

Endpoint

POST /inbound/{eventType}

Request

Component	Description
{eventType} (path)	The type of event being sent (e.g., manuscript.status.updated). Agreed upon during onboarding.
X-Api-Key (header)	Your API key, provided during onboarding.
Content-Type (header)	Must be application/json.
Request body	A JSON payload containing the event data.

Example

curl -X POST https://{base-url}/inbound/manuscript.status.updated \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "manuscriptId": "MS-2026-001",
    "status": "accepted",
    "updatedAt": "2026-02-26T12:00:00Z"
  }'

Replace {base-url} with the environment URL from the Overview.

Successful Response

A successful request returns 202 Accepted with the event ID:

{
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "Accepted"
}

The eventId is a unique identifier for the event. You can use it as a reference when communicating with ChronosHub support.

Deprecation hints (response headers)

When your payload matches a deprecated version of the event contract instead of the current active one, the request still succeeds with 202 Accepted so your integration keeps working. The response carries headers that tell you it's time to migrate:

Header	Description
X-Contract-Deprecated	true when the payload was matched against a deprecated contract version. Absent on Active matches.
X-Contract-Matched-Version	The contract version your payload matched (an integer, e.g. 1).
X-Contract-Active-Version	The current Active version you should migrate to (an integer, e.g. 3). Absent if no Active version exists for this event type.

Plan an update to align with the active contract version when you see these headers.

Error Responses

Status	Reason
400 Bad Request	Missing or empty payload, the event type isn't onboarded, the payload doesn't match any active or deprecated schema for the event type, or your account is inactive.
401 Unauthorized	Missing or invalid API key.
500 Internal Server Error	An unexpected error occurred on our side.

All error responses follow the Problem Details format. Two 400 shapes are common:

Schema validation failed — the event type is onboarded but the payload doesn't conform to the agreed JSON Schema:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Payload validation failed",
  "status": 400,
  "detail": "Payload for 'manuscript.status.updated' (Inbound) failed validation against every Active and Deprecated schema for the tuple.",
  "eventType": "manuscript.status.updated",
  "direction": "Inbound",
  "validationErrors": [
    "#/manuscriptId [required]: Required property is missing",
    "#/status [enum]: Value 'unknown' is not one of the allowed values"
  ],
  "traceId": "00-87ca4ab744fecd95c68d7198e8640de9-c9897de70d245733-01"
}

The validationErrors array lists each individual schema violation in the payload. Use it to fix your event before retrying.

No applicable contract — the event type isn't recognized:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "No applicable event contract",
  "status": 400,
  "detail": "No usable contract exists for 'unknown.event' (Inbound). The partner is posting an event type that has no Active or Deprecated schema.",
  "eventType": "unknown.event",
  "direction": "Inbound",
  "traceId": "00-87ca4ab744fecd95c68d7198e8640de9-c9897de70d245733-01"
}

This typically means the event type wasn't enabled for your integration. Contact ChronosHub support to add it.

The traceId field is a unique identifier for the request. Include it when contacting support so we can look into what went wrong.

Authentication

Every request must include a valid API key in the X-Api-Key header. Requests without a valid key are rejected with 401 Unauthorized.

API keys are provided during the onboarding process. See Partner Onboarding for details on how to obtain your API key.

Event Types

Event types are dot-separated identifiers that describe what happened (e.g., manuscript.status.updated). The available event types and their expected payload schemas are agreed upon between you and ChronosHub during onboarding.

Schema Versioning

Each event type can have multiple schema versions over its lifetime:

• Active — the current canonical schema for the event type. New integrations should target this version.
• Deprecated — a previous schema that ChronosHub still accepts so existing integrations keep working. You'll see deprecation headers on the response when your payload matches this; plan a migration to the Active version.
• Retired — no longer accepted. Payloads that only match a Retired schema receive 400 Payload validation failed.

ChronosHub publishes schema changes during onboarding. When a new Active version ships, your existing integration continues to work as long as the previous version stays Deprecated; the deprecation headers tell you when to update.