Skip to main content
Outbound webhooks notify your application when an EigenPal run is created or changes status. Use them when a run takes too long to keep an API request open and you do not want to poll the Runs API. Configure webhooks for your organization in Webhooks in the EigenPal dashboard. An endpoint can subscribe to either or both supported events:
  • run.created: EigenPal creates a top-level workflow or agent run.
  • run.status_changed: a top-level run moves from one persisted status to another.
Runs created internally by an action.invoke-workflow step do not emit webhook events.

​
Create an endpoint

1

Open Webhooks

Select Webhooks in the dashboard sidebar and choose Add webhook.
2

Enter the destination

Add a descriptive name and an HTTPS URL that accepts POST requests.
3

Choose events

Select run.created, run.status_changed, or both.
4

Add optional headers

If your receiver requires credentials, add them as custom headers, such as an Authorization header. EigenPal encrypts header values and does not display them after you save them. See Authentication for the supported options.
5

Store the signing secret

Copy the whsec_... signing secret from the creation dialog or the endpoint page. Use it to verify signatures on webhook requests from EigenPal.
To replace the signing secret, click Rotate next to Signing secret on the endpoint page. Choose when the current secret expires: in 24 hours or 1 hour to update your receiver without dropping events, or now if the secret leaked. See Rotate the signing secret.

​
Receive events safely

Webhook delivery is asynchronous and at least once. Your receiver should:
  1. Verify the signature.
  2. Store or deduplicate by the event id.
  3. Return a 2xx response quickly.
  4. Process expensive work asynchronously.
See the webhook receiver reference for request headers, event schemas, run statuses, signature verification code, and retry behavior.

​
Delivery settings

Choose Delivery settings on the Webhooks page to change how EigenPal delivers events to every endpoint in the organization:
  • Retries: Standard (7 attempts over about 31 hours), Quick (4 attempts over about 13 minutes), or No retries.
  • Request timeout: how long to wait for your server, from 1 to 120 seconds. The default is 10 seconds.
  • Private network delivery (self-hosted only): whether endpoints may resolve to internal addresses such as 10.x.x.x or a cluster service. It is on by default because receivers in a self-hosted deployment usually run in the same network.
Loopback, link-local and cloud metadata addresses (such as 127.0.0.1 and 169.254.169.254) are never allowed, even with private network delivery on: they reach the worker itself or the node’s credentials, never a receiver. Each failed attempt on an endpoint page explains the failure, for example Blocked: private network address or TLS handshake failed. It links here when a setting can fix it.

​
Self-hosted: pin settings for the deployment

As an operator, you can pin any of these settings for the whole deployment. A pinned setting shows a lock in the dashboard. You cannot change it there. With the Helm chart, set the webhooks values. They apply to both the app and the worker:
Without Helm, set WORKER_WEBHOOKS_ALLOW_PRIVATE_DESTINATIONS, WORKER_WEBHOOKS_REQUEST_TIMEOUT (milliseconds), and WORKER_WEBHOOKS_RETRY_SCHEDULE (comma-separated delays in milliseconds; the first is the initial attempt) on both the app and the worker. The worker logs the values it applies at startup (webhook-delivery-config).

​
Outbound security

Every delivery passes the same checks, regardless of the settings:
  • HTTPS only; URLs with credentials or fragments are refused.
  • The hostname is resolved once and the connection is pinned to the checked address, so a DNS answer cannot change between the check and the request.
  • EigenPal does not follow redirects.
  • Loopback, link-local and cloud metadata addresses are always refused. Hosted deployments also refuse every private range; self-hosted deployments allow private ranges unless private network delivery is turned off.
  • Requests time out, payloads are capped at 1 MB, and protocol headers (Host, Content-Length, webhook-*) cannot be overridden by custom headers.
  • EigenPal does not store response bodies for endpoints with custom headers, so a receiver that echoes request headers cannot leak credentials into the delivery log.
  • Endpoint editors can change the endpoint and rotate its signing secret. Only managers can delete it. Only organization owners and admins can change delivery settings. EigenPal records every change in the audit log.

​
Test an endpoint

Use Send test from an endpoint page. Test requests pass through the same queue, signing, security checks, and delivery history as production events and set test to true. The included run and automation IDs are synthetic and do not identify persisted resources.
Return 2xx as soon as your application durably accepts the event. A slow response can time out and cause a duplicate attempt, even if your application eventually completes its work.