Create a managed provider trigger registration

Mint a ProviderWebhookRegistration for one Automation WebhookSource and a catalog-admitted delivery mode. Both modes persist the desired config and fingerprint and place the ingest verification secret in CredentialCustody. Auto-registration claims and creates the provider hook, adopting only an exact callback key plus config fingerprint; polling persists an initial due state and remains pending until its first scheduler settlement, with no provider hook. Polling props are caller-supplied, publicly readable configuration and must not contain credentials; custody-held credentials never appear in the registration or response. Accepts an optional Idempotency-Key.

Checkfu support posture: alpha; hosted. Required evidence journey: automation-firing. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities.

POST /v1/automations/{id}/provider-webhook-registrations

Create a managed provider trigger registration

cURL

curl --request POST \
  --url https://api.checkfu.com/v1/automations/{id}/provider-webhook-registrations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --data '
{
  "webhook_source_id": "<string>",
  "connection_id": "<string>",
  "config": {
    "provider": "<string>",
    "resource": {
      "resource_type": "<string>",
      "external_id": "<string>"
    },
    "event_types": [
      "<string>"
    ],
    "polling_props": {}
  }
}
'

201

{
  "id": "<string>",
  "workspace_id": "<string>",
  "automation_id": "<string>",
  "webhook_source_id": "<string>",
  "connection_id": "<string>",
  "callback_key": "<string>",
  "config": {
    "provider": "<string>",
    "resource": {
      "resource_type": "<string>",
      "external_id": "<string>"
    },
    "event_types": [
      "<string>"
    ],
    "polling_props": {}
  },
  "config_fingerprint": "<string>",
  "status": "pending",
  "external_id": "<string>",
  "claim": {
    "epoch": 1,
    "operation": "create",
    "callback_key": "<string>",
    "config_fingerprint": "<string>",
    "expires_at": "<string>"
  },
  "last_verified_at": "<string>",
  "last_delivery_at": "<string>",
  "last_error": {
    "code": "<string>",
    "at": "<string>"
  },
  "version": 1,
  "created_at": "<string>",
  "updated_at": "<string>"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

checkfu-version · enum<string> · required

Available options: 2026-08-29

idempotency-key · string

Maximum string length: 255

Path Parameters

id · string · required

Pattern: ^auto_[0-9a-f]{32}$

Body

application/json

webhook_source_id · string · required

Pattern: ^whsrc_[0-9a-f]{32}$

connection_id · string · required

Pattern: ^conn_[0-9a-f]{32}$

config · object · required

Show child attributes

Response

201

application/json

Closed provider-trigger lifecycle and health for one Automation and WebhookSource. Custody-held credentials never appear; caller-supplied polling props are publicly readable and must not contain credentials.

Closed provider-trigger lifecycle and health for one Automation and WebhookSource. Custody-held credentials never appear; caller-supplied polling props are publicly readable and must not contain credentials.

id · string · required

Pattern: ^pwreg_[0-9a-f]{32}$

workspace_id · string · required

Pattern: ^wrkspc_[0-9a-f]{32}$

automation_id · string · required

Pattern: ^auto_[0-9a-f]{32}$

webhook_source_id · string · required

Pattern: ^whsrc_[0-9a-f]{32}$

connection_id · string · required

Pattern: ^conn_[0-9a-f]{32}$

callback_key · string · required

Pattern: ^pwcbk_[0-9a-f]{32}$

config · object · required

Show child attributes

config_fingerprint · string · required

Pattern: ^sha256:[0-9a-f]{64}$

status · enum<string> · required

Available options: pending, active, degraded, disabled, indeterminate, revoked, deleted

external_id · string | null · required

Pattern: ^[a-z0-9](?:[a-z0-9._-]{0,93})$

claim · object | null · required

Show child attributes

last_verified_at · string | null · required

A canonical UTC ISO-8601 timestamp with millisecond precision.

Maximum string length: 24

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$

last_delivery_at · string | null · required

A canonical UTC ISO-8601 timestamp with millisecond precision.

Maximum string length: 24

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$

last_error · object | null · required

Show child attributes

version · integer · required

Required range: x > 0

created_at · string · required

A canonical UTC ISO-8601 timestamp with millisecond precision.

Maximum string length: 24

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$

updated_at · string · required

A canonical UTC ISO-8601 timestamp with millisecond precision.

Maximum string length: 24

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$