Overview

Fired when a run fails critical cases or exceeds failure thresholds configured in policy.

Payloads are signed with HMAC-SHA256 using your webhook secret. Verify signatures before processing.

Who should read this

QA engineers, SREs, platform teams, and developers operating Zof Console and APIs.

When to use this workflow

Onboarding new team members to Zof terminology and workflows
Authoring internal runbooks aligned with Console labels
Designing CI/CD or webhook integrations against documented behavior

Step-by-step procedure

Subscribe

Include "run.failed" in webhook events array at registration.

Use Admin Center or POST /v1/webhooks.

Verify delivery

Validate HMAC-SHA256 signature header against raw request body.

Return HTTP 200 within 10 seconds; queue heavy work asynchronously.

Handle idempotently

Store event id; ignore duplicate deliveries with same id.

Reconcile with Console state if payload and UI disagree.

Key concepts

Organization scope: All Zof Console and API operations are isolated to your authenticated tenant.
Governed execution: Agent output and remediation follow policy packs with human approval when configured.

Best practices

Respond with 2xx within 10 seconds; process asynchronously
Store event id for idempotent handling
Rotate webhook secrets periodically from Admin Center

Example payload envelope

{
  "id": "evt_abc123",
  "type": "run.failed",
  "created": "2026-05-20T12:00:00Z",
  "data": {
    "object": {
      "id": "resource_id",
      "organization_id": "org_abc",
      "run_id": "run_xyz"
    }
  }
}