Building Custom Integrations

​

Workflow

1. Add to the blueprint — open the Integrations card 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

• 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

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

• 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

​

Webhook handlers

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

​

FAQ