ory/codex-plugins/ory-build-integration

Build an Ory Integration Into Your App

You are helping the user wire an Ory Network integration into their own application, reusing the proven patterns from the public ory/integrates repository. There is no contribution, registry, Maintained by:, or DCO concern here — you fetch the runnable subset of a template and adapt it in place.

This skill carries the workflow. The template files live in github.com/ory/integrates (branch main); fetch the ones you need so they stay current.

Precondition: ory/integrates must be reachable (public repo). If a fetch

fails, tell the user and stop — do not fabricate handler code.

Step 1 — Determine the type and app context

Pick the integration type from intent; ask directly if unclear.

Also establish: the app's framework/runtime, where the handler will live, and how it's deployed (these decide where you write files and how you mount the route).

Step 2 — Fetch the runnable subset

Pull only the files the user needs from _examples/_template-<type>/. Prefer raw fetch so you don't clone the whole repo into the user's project.

Raw file fetch (base URL https://raw.githubusercontent.com/ory/integrates/main/_examples/_template-<type>/):

BASE=https://raw.githubusercontent.com/ory/integrates/main/_examples/_template-webhook
mkdir -p ory-integration/webhook ory-integration/jsonnet
curl -fsSL "$BASE/ory-actions.yaml"          -o ory-integration/ory-actions.yaml
curl -fsSL "$BASE/jsonnet/identity.jsonnet"  -o ory-integration/jsonnet/identity.jsonnet
curl -fsSL "$BASE/webhook/server.ts"         -o ory-integration/webhook/server.ts
curl -fsSL "$BASE/webhook/package.json"      -o ory-integration/webhook/package.json
curl -fsSL "$BASE/webhook/tsconfig.json"     -o ory-integration/webhook/tsconfig.json
curl -fsSL "$BASE/webhook/.env.example"      -o ory-integration/webhook/.env.example

Sparse checkout (if the user prefers a git copy to diff against):

git clone --depth 1 --filter=blob:none --sparse https://github.com/ory/integrates /tmp/ory-integrates
git -C /tmp/ory-integrates sparse-checkout set _examples/_template-webhook
# then copy the files you want out of /tmp/ory-integrates/_examples/_template-webhook

Runnable subset per type (skip registry.entry.yaml.example, the Maintained by: README, and lockfiles — npm install regenerates the lock):

• webhook — ory-actions.yaml, jsonnet/identity.jsonnet,

webhook/{server.ts, package.json, tsconfig.json, .env.example}.

• config — ory-console-steps.md (no code; it's a Console walkthrough).
• http-event — ory-event-stream.yaml,

webhook/{server.ts, idempotency.ts, package.json, tsconfig.json, .env.example}.

Adapt the fetched handler into the user's app: integrate the route into their existing server if they have one, or run the webhook/ server standalone.

Step 3 — Wire it to the user's Ory project

• webhook — deploy the handler, then create an Ory Action pointing at it using

ory-actions.yaml as the template (set url to the deployed handler, set the X-Webhook-Secret value, and the matching ORY_WEBHOOK_SECRET in the handler's .env). Adjust jsonnet/identity.jsonnet to the body shape the handler expects. Apply via the Ory Console or the Ory CLI.

• config — follow ory-console-steps.md: configure the vendor side, then the

Ory Console (gateway/JWT validation, provider config, etc.). No code to deploy.

• http-event (Enterprise) — deploy the handler, then configure the

event-stream target from ory-event-stream.yaml (URL with embedded Basic Auth; set BASIC_AUTH_USER / BASIC_AUTH_PASSWORD in .env to match) and the event filter. Keep the idempotency.ts dedupe wired up — delivery is at-least-once.

Always verify the signature/secret path: webhook uses the X-Webhook-Secret header; http-event uses HTTP Basic Auth embedded in the configured URL.

Step 4 — Test locally

Stand up Ory and exercise the flow locally before pointing at production:

• Use ory-local-dev to run a local Ory stack (Kratos / Keto / Hydra +

gateway), then trigger the relevant flow and confirm the handler fires.

• Use ory-auth-setup when the app also needs Ory project / SDK setup wired up.

For a webhook, hit GET /health on the handler, then run the Ory flow and check the handler logs. For http-event, emit a test event and confirm both the dedupe and the downstream side effect.

What this skill does NOT do

• It does not create a contribution to ory/integrates (no registry.entry.yaml,

Maintained by:, SPDX, or DCO) — use ory-contribute-integration for that.

• It does not invent handler code — it fetches the real templates from

ory/integrates.

• It does not deploy to the user's infrastructure or modify their Ory project

without confirmation.