> ## Documentation Index
> Fetch the complete documentation index at: https://archie.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Building Custom Integrations

> Author custom integrations Archie does not ship.

When you need to talk to a service Archie does not provide a built-in for, build a custom integration. This page covers the developer workflow.

## Workflow

1. **Add to the blueprint** — open the [Integrations card](/features/blueprint/editing-integrations) and add a custom integration with a clear description of its purpose
2. **Run the build** — the generator scaffolds an integration module
3. **Implement the client** — fill in HTTP requests in the generated client wrapper
4. **Configure credentials** — store API keys or OAuth tokens in the integration settings
5. **Add webhook handlers** — if the service pushes events to you

## Generated scaffolding

A custom integration produces:

* `integrations/<name>/client.ts` — typed wrapper with placeholder methods
* `integrations/<name>/config.ts` — credential schema (what fields you store)
* `api/webhooks/<name>/route.ts` — webhook receiver (if your description mentioned receiving events)
* A registration entry so the integration appears in the **App services → Integrations** UI

## Implementing the client

Replace placeholder methods with real HTTP calls. Use the integration's auth pattern — Bearer token, OAuth, signed request, mTLS.

```typescript theme={null}
export class MyServiceClient {
  constructor(private config: MyServiceConfig) {}

  async sendEvent(event: Event) {
    const res = await fetch(`${this.config.baseUrl}/events`, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${this.config.apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(event),
    })
    if (!res.ok) throw new Error(`MyService error: ${res.status}`)
    return res.json()
  }
}
```

## OAuth-based integrations

For OAuth, the workflow includes:

* An install flow that redirects users to the third-party authorization page
* A callback route that exchanges the authorization code for tokens
* Token storage and refresh

Archie's OAuth helpers handle the flow scaffolding. {/* VERIFY: confirm OAuth helper API */}

## Webhook handlers

The generated webhook route verifies signatures. You implement the event handling — typically by dispatching to a [custom function](/features/backend/custom-functions/overview) so the receiver can acknowledge the delivery quickly while the work runs in the background:

```typescript theme={null}
export async function handler(req: Request, ctx: Context) {
  const event = await req.json()
  switch (event.type) {
    case "payment.succeeded":
      // your logic
      break
  }
  return new Response("ok")
}
```

## Publishing and reuse

Custom integrations are project-scoped. To reuse across projects in your workspace, package the client as a workspace shared module. {/* VERIFY: confirm workspace shared module support */}

## FAQ

<AccordionGroup>
  <Accordion title="How do I test webhook handlers locally?">
    Use a tunnel (ngrok, cloudflared) to expose your local dev server, or test against the preview environment.
  </Accordion>
</AccordionGroup>