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:- Accept HTTPS
POSTrequests. - Read and retain the exact request body bytes.
- Verify the timestamp and HMAC signature before parsing or processing the event.
- Deduplicate events by their stable
id. - Durably accept the event and return a
2xxresponse quickly. - Process expensive work asynchronously.
Content-Type: application/json and include these headers:
The stable event ID. It matches the
id field in the body and forms part of
the signed message.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.Event envelope
Every request has a versioned JSON envelope:Envelope fields
Whentest 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.
Run fields
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.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.
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:-
Take the part of the
whsec_...secret after thewhsec_prefix and base64-decode it. The decoded bytes are the HMAC key. -
Build the signed message from the
webhook-idheader, thewebhook-timestampheader, and the raw request body, separated by periods: -
Compute HMAC-SHA256 of the message, base64-encode it, and prefix it with
v1,.
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.
Rotate the signing secret
Rotate the secret regularly, or immediately if it is exposed:- On the endpoint page, next to Signing secret, click Rotate.
- 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.
- Copy the new secret and deploy it to your receiver.
- 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.
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 with401 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, andcreatedAtinstead of inferring lifecycle order from delivery order. - Return
2xxas soon as you durably accept the event. - Process expensive work after acknowledging the request.
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.