Workflow Effect Webhooks - Cedar.AI Documentation

Overview

Cedar’s workflow automation can send real-time event notifications to your systems via webhooks. When a configured event occurs (such as a car being placed at a station), Cedar POSTs a signed JSON payload to your endpoint.

Webhooks let you integrate Cedar events into your own systems — ERP platforms, notification services, or any HTTP endpoint that can receive JSON.

How It Works

Event Triggers

A workflow event fires in ARMS (e.g. car placed at a station).

Payload Built

Cedar constructs a JSON payload with event details, equipment information, and timestamps.

Signed & Sent

The payload is signed with Ed25519 and POSTed to your configured webhook URL over HTTP/2 (with automatic fallback to HTTP/1.1).

You Verify

Your endpoint verifies the signature using Cedar’s public key, then processes the event.

Configuration

Each webhook effect requires one input when you set up the workflow in ARMS:

Input	Description
Webhook URL	The HTTPS endpoint where Cedar sends the POST request.

Always use HTTPS endpoints in production.

HTTP Headers

Every webhook request includes these headers:

Header	Description	Example
`Content-Type`	Always `application/json`	`application/json`
`X-Webhook-Timestamp`	Unix epoch (seconds) when the request was sent	`1709651400`
`X-Webhook-Signature`	Base64-encoded Ed25519 signature	`a3F0eGp...`
`X-Webhook-KeyId`	Identifier for the signing key used	`cedar-webhooks-2026`
`X-Webhook-Id`	UUID v4 for deduplication	`550e8400-e29b-41d4-...`

Signature Verification

Cedar signs every webhook payload with Ed25519 so you can verify that requests genuinely came from Cedar and haven’t been tampered with.

Public Key

Use this public key to verify webhook signatures:

MCowBQYDK2VwAyEAuePoYCHOJvZJzlnsxfEv3mtssVKxkDAZsDHUE9Z3TW8=

Store this public key in your application configuration. It does not change between environments.

How Signing Works

The signature covers a combination of the timestamp, key ID, and the request body:

signing_input = TIMESTAMP + "." + KEY_ID + "." + CANONICAL_JSON_BODY

Where:

TIMESTAMP is the value of the X-Webhook-Timestamp header (string)
KEY_ID is the value of the X-Webhook-KeyId header (string)
CANONICAL_JSON_BODY is the raw request body bytes (JSON with sorted keys and no extra whitespace)

The signature is the Ed25519 signature of signing_input, base64-encoded in the X-Webhook-Signature header.

Security Best Practices

Verify every request

Always verify the X-Webhook-Signature before processing the payload. This confirms the request came from Cedar and hasn’t been modified in transit.

Check timestamps for replay protection

Compare X-Webhook-Timestamp against the current time. Reject requests older than 5 minutes to prevent replay attacks.

Use X-Webhook-Id for deduplication

Network retries can cause duplicate deliveries. Store processed X-Webhook-Id values and skip duplicates.

Respond quickly

Return a 2xx response within 30 seconds. If processing takes longer, acknowledge the request immediately and process asynchronously.

Shared Payload Fields

Every webhook payload includes the following top-level fields in addition to the event-specific ones documented on each webhook’s page.

actor

Identifies the user or system actor that caused the event to fire. Useful for auditing, attribution, and downstream filtering.

"actor": {
  "resource_type": "User",
  "resource_id": 12345,
  "display_name": "ops@customer.com"
}

Field	Type	Description
`resource_type`	string	The kind of actor. See the table below for known values.
`resource_id`	integer or string	The actor’s internal identifier. Type depends on `resource_type` — typically integer for users and carriers, string for X12 messages.
`display_name`	string	Human-readable label for the actor. Best-effort; falls back to a stable synthetic label when no name is available.

Known resource_type values:

`resource_type`	When emitted	`display_name` source
`User`	A user triggered the event directly (e.g. placing a car in the UI).	`display_name`, falling back to `email`.
`WorkflowTrigger`	Another workflow effect fired this event transitively.	Workflow trigger name.
`WorkflowInvocation`	A specific workflow invocation produced the event (cascading invocations).	Workflow invocation name.
`Carrier`	An automated carrier-level process (not a human) initiated the event.	Carrier name, falling back to carrier code.
`X12Message`	An inbound EDI (X12) message drove the state change that fired the event.	`X12Message<{resource_id}>` synthetic label.

actor is null for cron-scheduled workflows or other system-initiated events that have no identifiable actor. The actor key is always present in the payload, so your integration can rely on it being set (possibly to null).

Retry Behavior

Cedar automatically retries webhook deliveries when transient failures occur. Retries happen in two phases: inline retries during the initial delivery, and deferred retries scheduled over the next 24 hours.

Inline retries

Condition	Behavior
Server errors (5xx)	Retried up to 5 total attempts
Timeouts & network errors	Retried up to 5 total attempts
HTTP 408 and 429	Retried up to 5 total attempts
Other client errors (4xx)	Not retried inline — fix the issue and redeploy
TLS / SSL certificate errors	Not retried — the endpoint certificate is invalid

Inline retries use exponential backoff (1—10 seconds between attempts). The first attempt uses a 30-second timeout; retries use a shorter 5-second timeout. If HTTP/2 negotiation fails with a protocol error, Cedar automatically downgrades to HTTP/1.1 on the next attempt.

Deferred retries

If all inline attempts fail, Cedar schedules deferred retries on an hourly cadence:

Retried once per hour for up to 24 hours or 8 attempts, whichever comes first.
Each deferred attempt is re-signed with a fresh X-Webhook-Timestamp (because receivers reject stale signatures) but keeps the same X-Webhook-Id so your endpoint can deduplicate.
After the retry window closes, the delivery is marked abandoned and no further attempts are made.

The same X-Webhook-Id is sent on every inline and deferred retry attempt. Store processed IDs on your side to deduplicate safely.

Available Webhook Effects

Car Actually Placed

Fires when a car is placed at a station or track. Includes equipment details, station, and loaded/empty status.

Train Arrival

Fires when a train arrives at a station. Includes equipment list, station, loaded/empty status, and train number.

Train Set

Fires when a train consist is defined. Includes wagon list, departure/arrival stations with names, and train ID.

Train Departure

Fires when a train departs from a station or customer location. Includes equipment list, station, customer/serving location, loaded/empty status, and train number.

Questions?

For questions about webhook configuration or integration, contact your Cedar account team or email support@cedarai.com.

​Overview

​How It Works

​Configuration

​HTTP Headers

​Signature Verification

​Public Key

​How Signing Works

​Security Best Practices

​Shared Payload Fields

​actor

​Retry Behavior

​Inline retries

​Deferred retries

​Available Webhook Effects

Car Actually Placed

Train Arrival

Train Set

Train Departure

​Questions?

Overview

How It Works

Configuration

HTTP Headers

Signature Verification

Public Key

How Signing Works

Security Best Practices

Shared Payload Fields

actor

Retry Behavior

Inline retries

Deferred retries

Available Webhook Effects

Questions?