Tutorial

Conecta tu app

Haz que tu propio producto pueda ser controlado por un trabajador. Dos direcciones que puedes combinar: saliente (un trabajador llama a tu API) y entrante (tu app activa a un trabajador).

Cómo funciona

  • Saliente — una conexión de API genérica permite que un trabajador vinculado llame a la API HTTP de tu app (publicar contenido, actualizar un ticket, …) mediante su herramienta api_request. Las llamadas están protegidas contra SSRF mediante una lista de hosts permitidos; tus credenciales se cifran en reposo.
  • Entrante — una conexión de Webhook te da una URL de endpoint firmada. Tu app envía un evento por POST y se convierte en una tarea para el trabajador vinculado.

Seguridad

Las escrituras del trabajador siguen respetando su nivel de autonomía — las acciones contra tu app requieren aprobación a menos que el trabajador esté configurado para ejecución automática. La protección SSRF bloquea direcciones privadas/internas.

Tutorial 1 — deja que un trabajador gestione tu sitio web

Conecta la API de tu sitio y vincúlala a un trabajador:

import { CreateWorker } from "@createworker/sdk";
const cw = new CreateWorker({ apiKey: process.env.CREATEWORKER_API_KEY! });

const conn = await cw.integrations.createApiConnection({
  displayName: "My portfolio",
  baseUrl: "https://api.myportfolio.com",
  allowedHosts: ["api.myportfolio.com"],   // SSRF allowlist (required)
  authMode: "bearer",
  bearerToken: process.env.MY_PORTFOLIO_TOKEN!,
});

await cw.integrations.bind({ workerId: "wrk_…", connectionId: conn.id, purpose: "OUTBOUND" });

Ayuda al trabajador a descubrir tus endpoints subiendo tu referencia de API a su conocimiento:

await cw.knowledge.create({
  title: "Portfolio API",
  content: "POST /projects { title, body, coverImageUrl } — create a project. PATCH /projects/{id} …",
});

Ahora una tarea puede actuar sobre tu sitio — el trabajador emite llamadas api_request contra tu API:

const task = await cw.tasks.create({
  workerId: "wrk_…",
  title: "Publish a new project called 'Aurora' with a short write-up about the redesign.",
});
const done = await cw.tasks.waitForTask(task.id);
if (done.status === "PROPOSED") await cw.approvals.create(task.id, { decision: "APPROVE" });

Tutorial 2 — deja que tu app active a un trabajador

Crea una conexión de webhook y vincúlala (entrante):

const wh = await cw.integrations.createWebhookConnection({
  displayName: "Helpdesk",
  inbound: { authMode: "signature", generateSecret: true },
});
await cw.integrations.bind({ workerId: "support_…", connectionId: wh.id, purpose: "INBOUND" });

// Store these (shown once):
//   wh.inbound.endpointUrl   → where your app POSTs events
//   wh.signingSecret         → to HMAC-sign those requests

Desde tu app, envía por POST un evento firmado cuando algo suceda — se convierte en una tarea:

import { signInboundRequest } from "@createworker/sdk";

const { body, headers } = signInboundRequest(
  {
    externalId: "ticket-123",            // idempotency key
    type: "ticket.created",
    task: { title: "New ticket #123", description: "Customer can't reset their password." },
    payload: { ticketId: "123", email: "[email protected]" },
  },
  process.env.CW_INBOUND_SECRET!,        // = wh.signingSecret
);

await fetch(endpointUrl, { method: "POST", headers, body });

Tutorial 3 — el ciclo completo de helpdesk

Vincula un trabajador de soporte a ambas conexiones (usa purpose: "BOTH", o vincula el webhook como INBOUND y la API genérica como OUTBOUND). Un webhook de nuevo ticket crea una tarea → el trabajador redacta una respuesta → la publica de nuevo en tu helpdesk con una llamada api_request. Con las aprobaciones activadas, revisas cada respuesta antes de enviarla; con ejecución automática, se ejecuta sin supervisión.

El mismo patrón, cualquier app

Los mismos dos primitivos conectan un CMS, un CRM, un panel de administración interno o cualquier API HTTP. Limita la conexión solo a los hosts y credenciales que el trabajador necesita.

Referencia

Consulta la página del SDK para ver todos los métodos integrations.*, o la referencia de la API para POST /v1/integrations/connections.