Trigger Automations from providers

provider account and hook or polling lifecycle
  → ProviderWebhookRegistration
  → WebhookSource bound to a governed Connection
  → signed Automation ingress and dedupe
  → Automation firing authority
  → AutomationRun
  → Session with frozen AgentVersion + Environment

import { Checkfu } from "@checkfu/sdk"

const checkfu = new Checkfu({ apiKey: process.env.CHECKFU_API_KEY })
const eventType = process.env.PROVIDER_EVENT_TYPE!

const catalog = await checkfu.automations.providerWebhookCatalog.list(automationId, {
  provider,
})

const selected = catalog.events.find(
  (event) =>
    event.event_type === eventType &&
    event.resources.some(
      (resource) =>
        resource.resource_type === "repository" &&
        resource.external_id === "octo/repo",
    ),
)

if (
  selected === undefined ||
  (selected.capability !== "auto_registration" && selected.capability !== "polling")
) {
  throw new Error("This trigger requires the manual URL path or is unsupported")
}

const registration =
  await checkfu.automations.providerWebhookRegistrations.create(
    automationId,
    {
      webhook_source_id: webhookSourceId,
      connection_id: connectionId,
      config: {
        provider: catalog.provider,
        resource: {
          resource_type: "repository",
          external_id: "octo/repo",
        },
        event_types: [selected.event_type],
      },
    },
    { idempotencyKey: `provider-trigger-${automationId}` },
  )

import { relayProviderWebhook } from "@checkfu/integration-host"

const result = await relayProviderWebhook({
  delivery: { body: rawBody, headers: providerHeaders },
  automationIngestSecret: process.env.CHECKFU_AUTOMATION_SECRET!,
  verifyProvider: ({ body, headers }) => verifyProviderSignature(body, headers),
  forwardToAutomation: ({ body, checkfuSignature }) =>
    fetch(`${process.env.CHECKFU_API}/v1/ingest/automations/${automationId}`, {
      method: "POST",
      headers: {
        "content-type": "application/json",
        "checkfu-version": "2026-08-31",
        "checkfu-signature": checkfuSignature,
      },
      body,
    }),
})

if (result.kind !== "forwarded") {
  throw new Error(`Provider delivery refused: ${result.kind}`)
}