Forgeplane webhook event reference

Forgeplane webhook events are JSON HTTP POST deliveries. A webhook can subscribe to one or more supported event types; the event name identifies the lifecycle change that caused the delivery.

Use Webhooks for endpoint configuration and receiver operations.

Supported event types

Run lifecycle

Event	Description
run.created	A run was created or queued.
run.started	A worker started execution.
run.pending_approval	A run entered approval-pending state.
run.completed	A run completed successfully.
run.failed	A run ended as failed, canceled, or timed out.
run.deleted	A run record was deleted.

Drift lifecycle

Event	Description
drift.finding.created	A new drift finding was detected.
drift.finding.updated	Drift finding metadata or status changed.
drift.finding.action.requested	A convergence action was requested.
drift.finding.resolved	A drift finding was resolved.
drift.finding.suppressed	A drift finding was suppressed.
drift.finding.reopened	A suppressed finding was reopened.

Common payload envelope

All events use the same envelope:

{
  "event_type": "run.pending_approval",
  "occurred_at": "2026-03-22T14:30:00Z",
  "run_id": "run_abc123",
  "project_id": "proj_xyz789",
  "status": "pending_approval"
}

Field	Type	Description
event_type	string	Webhook event identifier.
occurred_at	string	ISO-8601 event timestamp.
run_id	string	Run identifier.
project_id	string	Project identifier.
status	string	Run or finding status at emit time.

Signature verification

Every request includes X-Forgeplane-Signature. Its value is an HMAC-SHA256 signature over the raw request body, calculated with the webhook secret:

X-Forgeplane-Signature: sha256=<hmac hex>

Verify the signature against the raw bytes before parsing the JSON or performing an event action. Compare signatures in constant time.

Retry behavior

Retry behavior is configured per webhook:

Setting	Description
max_attempts	Maximum number of delivery attempts.
retry_delays_seconds	Delay schedule between attempts, in seconds.

Forgeplane retries after a non-2xx response or network failure. If retry_delays_seconds contains fewer entries than max_attempts, the final delay value is reused for the remaining attempts.