Webhooks

Webhook subscriptions currently support calculation.succeeded and calculation.failed. Events are environment-isolated. Future event names are not exposed until their producing workflows and public payload contracts are available.

The canonical result commits before delivery is enqueued. Destination failure never rolls back a calculation. Delivery uses finite exponential backoff and enters dead_letter after the configured maximum attempts. Redirects and prohibited private/link-local targets are denied by the SaaS network policy.

Creating a webhook endpoint#

Choose Test or Live when the endpoint is created. That environment cannot be changed in place; create a new endpoint for a different environment. URL and event subscriptions may be updated. Pending deliveries retain their immutable event environment and content, while a later attempt uses the endpoint's current URL.

Organization managers create Test and Live endpoints in ErgOps Embedded → Developers. Live destinations require HTTPS. Choose only the supported events needed by the integration.

The signing secret is shown once. Store it separately from API keys in a server-side secret manager. Endpoint capacity comes from the active contract. Updating a URL or event subscription does not grant any organization permission.

ErgOps rejects credential-bearing URLs, loopback, link-local, private network destinations, unsupported schemes and unsafe ports under the SaaS network policy.

Webhook events#

calculation.succeeded#

Emitted after the canonical calculation and its environment-specific persistence commit. The payload contains the customer-safe calculation result and request correlation ID.

calculation.failed#

Emitted for a handled calculation failure after authentication and request correlation. It contains a stable safe error code and external reference where available; stack traces, SQL and secrets are excluded.

Replay protection#

Deduplicate with X-ErgOps-Webhook-Id, verify the timestamp tolerance and verify the signature over the raw body before parsing JSON. Event IDs remain stable across retry attempts.

Webhook retries and failures#

Non-2xx responses and network timeouts schedule exponential backoff. Redirects are not followed. Attempt count, safe error category, response status and next attempt time are retained without response bodies. After the finite maximum, delivery becomes dead_letter and requires operator action.

Consumers should acknowledge quickly, process asynchronously and use X-ErgOps-Webhook-Id for their own idempotency.