External Checks

What Are External Check Providers?

External check providers let you integrate custom approval systems that Forgecroft doesn’t natively support. Examples:

Your internal compliance platform
A ServiceNow approval workflow
A custom security review system

The Callback Flow

Plan completes
  ↓
Forgecroft creates an external check requirement
  ↓
Forgecroft POSTs to provider's callback_url with run details
  ↓
Provider evaluates the run (async)
  ↓
Provider POSTs decision back to Forgecroft
  ↓
Forgecroft processes: pass → satisfy, fail → reject

Registering a Provider

POST /external-check-providers
{
  "name": "compliance-platform",
  "callback_url": "https://compliance.example.com/api/check",
  "description": "Internal compliance platform",
  "timeout_hours": 48,
  "escalation_action": "reject"
}

Field	Type	Required	Default	Description
`name`	string	Yes	—	Must be unique within org
`callback_url`	string	Yes	—	Must be HTTPS
`description`	string	No	—
`timeout_hours`	int	No	24	Hours before escalation
`escalation_action`	string	No	`reject`	`auto_approve`, `escalate_to`, or `reject`

Storing the Provider Secret

POST /external-check-providers/{id}/secret
{
  "api_token": "your-secret-token"
}

The token is stored in a secure vault (OpenBao). It is used to sign the HMAC tokens that Forgecroft sends to the provider.

Scoping the Provider

Attach the provider to org, project, or workspace scopes:

POST /external-check-providers/{id}/scopes
{
  "scope_type": "workspace",
  "scope_id": "workspace-uuid"
}

The provider only evaluates runs within its attached scopes.

Provider Callback to Forgecroft

When the provider has evaluated the run, it POSTs back:

POST /runs/{id}/external-checks/{providerId}
Authorization: Bearer <HMAC-SHA256(providerID:runID, providerSecret)>
{
  "decision": "pass",
  "reason": "Compliance check passed"
}

The Bearer token is an HMAC-SHA256 signature of providerID:runID using the provider’s secret.

Field	Type	Required	Description
`decision`	string	Yes	`pass` or `fail`
`reason`	string	No	Explanation of the decision

On pass: the requirement is satisfied. If all stages are complete, the run transitions to completed.

On fail: the requirement and the run are rejected.

Notification Payload

When Forgecroft notifies the provider, the request includes:

Body: Run summary with added, changed, destroyed counts, workspace ID, run ID, and a pre-computed callback_url with callback_token
Header: X-Forgecroft-Signature: sha256=<hex> — an HMAC-SHA256 signature of the entire request body using the provider’s secret

The payload includes only plan summary counts, not the full plan JSON. This limits data exposure to external systems. If the provider needs detailed plan data, it should fetch it via a separate authenticated API call.

Providers should validate the X-Forgecroft-Signature header in addition to using the Bearer token for callbacks. This provides defense-in-depth against replay attacks.

Multiple Providers

Multiple external check providers can be configured and attached to the same workspace. Each receives a separate notification and responds independently. All must pass for the requirement to be satisfied.

Updating a Provider

PATCH /external-check-providers/{id}
{
  "callback_url": "https://new-compliance.example.com/api/check",
  "enabled": false
}

Mutable fields: name, description, callback_url, enabled, timeout_hours, escalation_action.

Listing Provider Scopes

GET /external-check-providers/{id}/scopes

Returns all scope attachments for the provider.

POST /external-check-providers — Register a provider
GET /external-check-providers — List providers
POST /external-check-providers/{id}/secret — Store the API token
POST /external-check-providers/{id}/scopes — Attach to a scope
GET /external-check-providers/{id}/scopes — List scope attachments
POST /runs/{id}/external-checks/{providerId} — Provider callback (HMAC auth)