Skip to main content
EigenPal sends webhook events as HTTPS POST requests with a JSON body. This page defines the receiver contract, event schemas, signature verification, and delivery behavior. For dashboard setup and testing, see Receive run events with webhooks.

Request contract

Your receiver must:
  1. Accept HTTPS POST requests.
  2. Read and retain the exact request body bytes.
  3. Verify the timestamp and HMAC signature before parsing or processing the event.
  4. Deduplicate events by their stable id.
  5. Durably accept the event and return a 2xx response quickly.
  6. Process expensive work asynchronously.
Requests use Content-Type: application/json and include these headers:
string
required
The stable event ID. It matches the id field in the body and forms part of the signed message.
string
required
The Unix timestamp, in seconds, when the delivery attempt was signed.
string
required
One or more space-delimited signatures, each formatted as v1,<base64 HMAC-SHA256>. The header includes two signatures while a rotated secret is still active.
string
required
Identifies the EigenPal webhook sender and release.
Requests also include any custom headers you configure for the endpoint.

Event envelope

Every request has a versioned JSON envelope:

Envelope fields

string
required
Stable event ID with a whev_ prefix. Use this value as the idempotency key.
run.created | run.status_changed
required
Identifies the event schema.
string
required
Version of the webhook wire contract. The current version is 2026-07-01.
string
required
ISO 8601 timestamp of event creation.
boolean
required
true for events created with Send test; otherwise false.
When test is true, data.run contains synthetic sample data. Its run and automation IDs do not identify persisted resources. Verify and acknowledge the request normally, but do not fetch or process the sample as a real run.
object
required
Event-specific payload.

Run fields

string
required
Run ID.
string
required
Automation that owns the run (wf_... for workflows, agent_... for agents).
workflow | agent
required
Runtime used by the automation.
string
required
Current persisted run status.
string
required
How the run was started, such as api, manual, email, or cron.
string[]
required
Tags the run was started with (the tags field of POST /api/v1/runs), or an empty array. Tags remain when output is omitted. Use them to correlate events with records in your system.
string
required
ISO 8601 timestamp of run creation.
string | null
required
ISO 8601 timestamp for when execution started, or null.
string | null
required
ISO 8601 timestamp for when the run reached a terminal status, or null.
unknown
Public run output, when available and small enough to include.
boolean
true when EigenPal removes output to keep the complete event within the payload limit. Retrieve the canonical result with GET /api/v1/runs/{id}.

Event types

run.created

EigenPal sends this event when it durably creates a top-level workflow or agent run. data.run contains the initial run snapshot. Most workflow runs are already pending when this event is sent; agent runs can initially be created while preparation completes. This event does not include previousStatus or currentStatus. Test deliveries use the same schema with synthetic run data.

run.status_changed

EigenPal sends this event whenever a top-level run moves from one persisted status to another. Test deliveries simulate this transition with synthetic run data.
string
required
Status the run moved from.
string
required
Status the run moved to. This matches data.run.status.
Runs created internally by an action.invoke-workflow step and evaluation runs do not emit webhook events.

Run statuses

  • created: The run exists and is being prepared before it enters the queue.
  • pending: The run is queued and eligible for a worker.
  • running: A worker is executing the run.
  • waiting: The workflow is paused for a human, tool, or step continuation. Not all run types use this status.
  • finalizing: Primary execution has finished, but outputs or other post-run work are still being saved.
  • completed: The run finished successfully. Terminal.
  • failed: The run ended because of an error or timeout. Terminal.
  • cancelled: The run was cancelled before completion. Terminal.
  • rejected: The run was refused before it started, for example because of an inbound email policy. Terminal.
queued is an execution phase, not a run status. The externally visible status for a run waiting in the queue is pending.

Authentication

Your receiver can authenticate EigenPal webhook requests in two ways. Use both when your network or API gateway requires its own credential. Always verify the signature, even when you also use a custom header. A static header only shows that the sender knows the credential. The signature protects the event ID, timestamp, and body from modification. Reject timestamps outside your accepted time window. Deduplicate events by event ID to avoid processing a replayed or retried request twice. See Verify webhook signatures. EigenPal encrypts custom header values at rest and does not display them after you save them. Custom headers can’t use protocol header names such as Host, Content-Length, Content-Type, or User-Agent, or any name that starts with webhook-. EigenPal compares names case-insensitively. It does not store response bodies for endpoints that have custom headers, so a receiver that echoes request headers can’t expose credentials in the delivery log. EigenPal does not support mutual TLS (client certificates) or the OAuth 2.0 client credentials grant for webhook deliveries.

Verify webhook signatures

EigenPal signs requests as defined by Standard Webhooks, so you can verify them with any Standard Webhooks library instead of writing your own check. Verify the signature and timestamp before you process an event. To compute a signature:
  1. Take the part of the whsec_... secret after the whsec_ prefix and base64-decode it. The decoded bytes are the HMAC key.
  2. Build the signed message from the webhook-id header, the webhook-timestamp header, and the raw request body, separated by periods:
  3. Compute HMAC-SHA256 of the message, base64-encode it, and prefix it with v1,.
The webhook-signature header can contain more than one signature, separated by spaces. Accept the request when any of them matches. These receivers check both authentication methods: the optional Authorization header you configured on the endpoint, and the signature. The Node.js and Python examples use the official Standard Webhooks libraries (standardwebhooks on npm and PyPI). The C# example implements the algorithm above with .NET’s built-in cryptography and has no dependencies. Each receiver rejects requests with timestamps more than five minutes old.
Use the raw bytes your framework supplies. Parsing JSON and serializing it again can change whitespace or key ordering and invalidate the signature. Parse the body only after verification succeeds. Reject missing, malformed, or stale signature headers. Store the signing secret outside source control.

Rotate the signing secret

Rotate the secret regularly, or immediately if it is exposed:
  1. On the endpoint page, next to Signing secret, click Rotate.
  2. Under Current secret expires, choose when the current secret stops signing requests:
    • In 24 hours (default) or In 1 hour: EigenPal signs every request with both the new and the current secret until then, so a receiver that uses either one keeps accepting events.
    • Now: the current secret stops working immediately. Choose this if the secret leaked. Your receiver rejects events until it has the new secret.
  3. Copy the new secret and deploy it to your receiver.
  4. If you chose In 24 hours or In 1 hour, accept a request signed with either the new or the old secret for a few minutes after deploying. A delivery that was already in progress when you rotated carries only the old secret’s signature. If you chose Now, accept only the new secret, and redeliver any in-progress delivery that your receiver rejected.
Rotating again before the old secret expires retires it immediately. Only the newest two secrets sign a request.

Upgrade a receiver that expects hex signatures

Earlier releases sent a hex-encoded signature and used the secret text itself as the HMAC key. If your receiver uses that format, update it to the algorithm above. Your secret has not changed, but the dashboard now shows it in standard base64, which is the form Standard Webhooks libraries expect. Both forms decode to the same key. Requests your receiver rejected with 401 or 403 before you updated it are not retried. After updating, open the endpoint page and redeliver those deliveries.

Delivery and retries

Delivery is asynchronous and at least once. Expect duplicate events. Events can arrive out of order.
  • Deduplicate by the event id.
  • Use previousStatus, currentStatus, and createdAt instead of inferring lifecycle order from delivery order.
  • Return 2xx as soon as you durably accept the event.
  • Process expensive work after acknowledging the request.
Any 2xx response marks a delivery successful. EigenPal retries network failures, timeouts, 408, 425, 429, and 5xx responses. Other 4xx responses end automatic delivery. EigenPal does not follow redirects. The retry schedule is an organization setting (Webhooks > Delivery settings): A valid Retry-After header (seconds or an HTTP date) lengthens the next wait but never shortens it below the schedule. Each request times out after 10 seconds by default; the timeout is also an organization setting. If your receiver sometimes gets an event before it can match the run (for example, while it is still storing the run ID returned by POST /v1/runs), respond with 503 and Retry-After. EigenPal retries unless the organization’s retry policy is No retries. Use data.run.automationId to ignore events for workflows your receiver does not handle. Manual redelivery preserves the event ID and payload, so normal deduplication still applies.