Forgeplane webhooks
Forgeplane webhooks send signed HTTP POST notifications to an external endpoint when a run or drift event occurs. Configure the subscription and retry policy in Forgeplane, then verify the raw request body before processing it.
See the Webhook event reference for the canonical event names and payload envelope.
Configure a webhook
Section titled “Configure a webhook”Each webhook has these settings:
| Field | Type | Purpose |
|---|---|---|
url |
string | Destination HTTP endpoint. |
secret |
string | Shared secret used to calculate request signatures. |
event_types |
string[] | Events delivered to this endpoint. |
max_attempts |
integer | Maximum delivery attempts for one event. |
retry_delays_seconds |
integer[] | Delay schedule between attempts. |
is_active |
boolean | Enables or disables delivery. |
Select only the event types the receiver needs. Keep the signing secret separate from the payload and rotate it through the normal connection or secret-management process.
Subscribe to events
Section titled “Subscribe to events”Run events
Section titled “Run events”| Event | Trigger |
|---|---|
run.created |
A run is created or queued. |
run.started |
A worker starts execution. |
run.pending_approval |
A run enters approval-pending state. |
run.completed |
A run succeeds. |
run.failed |
A run fails, times out, or is canceled. |
run.deleted |
A run record is deleted. |
Drift events
Section titled “Drift events”| Event | Trigger |
|---|---|
drift.finding.created |
A drift finding is created. |
drift.finding.updated |
A drift finding changes. |
drift.finding.action.requested |
A convergence action is requested. |
drift.finding.resolved |
A drift finding is resolved. |
drift.finding.suppressed |
A drift finding is suppressed. |
drift.finding.reopened |
A suppressed finding is reopened. |
Verify a delivery
Section titled “Verify a delivery”Every delivery includes:
X-Forgeplane-Signature: sha256=<hmac hex>Compute HMAC-SHA256 over the raw request body with the webhook secret. Compare the expected value and the header with a constant-time comparison. Verify the signature before parsing or acting on the JSON payload.
The common payload envelope includes event_type, occurred_at, run_id, project_id, and status. Event-specific details are documented in the Webhook event reference.
Retry and delivery history
Section titled “Retry and delivery history”Forgeplane retries a delivery after a non-2xx response or a network failure. The webhook’s max_attempts and retry_delays_seconds values control the retry schedule; they are not global constants.
Delivery history records:
- attempt number;
- success or failure;
- response status code;
- response body excerpt;
- transport or request error message; and
- delivery timestamp.
Use delivery history to distinguish a receiver response from a network failure before changing the subscription or retry policy.