Developers

Webhooks

Event-driven notifications for run completion, failures, and governance events.

Overview

Webhooks deliver real-time notifications to your HTTPS endpoints when platform events occur, reducing polling and enabling incident response automation.

Each endpoint has a signing secret; validate the signature before processing payload to prevent spoofing.

Step-by-step procedure

Register endpoint

Admin → Developer → Webhooks or POST /v1/webhooks.

Select events and generate secret.

Implement handler

Verify signature header.

Return 200 quickly; queue heavy processing.

Test delivery

Use test event from Console or API.

Confirm receipt in your logs.

Key concepts

run.completed: Validation run finished (any terminal status).
run.failed: Run failed with one or more case failures.
remediation.plan_pending: Remediation plan awaiting human approval.
agent.offline: Execution agent missed heartbeat threshold.

Design for duplicate, delayed, and missing delivery

Confirm the supported event schema, authentication or signature method, delivery behavior, and retry policy before building a receiver. Do not assume exactly-once delivery or ordering unless the documented contract provides it.

Validate a representative event and its authenticity, restrict payload logging, and make processing idempotent where repeated delivery is possible. Track delivery failures and reconcile important state with the authoritative service instead of treating the absence of an event as proof that nothing changed.

Was this page helpful?