Tutorial

Koppel je app

Maak je eigen product bestuurbaar door een werknemer. Twee richtingen die je kunt combineren: uitgaand (een werknemer roept je API aan) en inkomend (je app activeert een werknemer).

Hoe het werkt

  • Uitgaand — een Generic API-verbinding laat een gekoppelde werknemer de HTTP-API van je app aanroepen (content publiceren, een ticket bijwerken, …) via zijn api_request-tool. Aanroepen zijn SSRF-beveiligd via een toegestane-hosts-lijst; je gegevens worden versleuteld opgeslagen.
  • Inkomend — een Webhook-verbinding geeft je een ondertekende endpoint-URL. Je app stuurt een event via POST en dit wordt een taak voor de gekoppelde werknemer.

Veiligheid

Schrijfacties van een werknemer respecteren nog steeds het autonomieniveau van de werknemer — acties tegen je app vereisen goedkeuring tenzij de werknemer is ingesteld op automatisch uitvoeren. SSRF-bescherming blokkeert private/interne adressen.

Tutorial 1 — laat een werknemer je website beheren

Koppel de API van je site en bind deze aan een werknemer:

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" });

Help de werknemer je endpoints te ontdekken door je API-referentie te uploaden naar zijn kennis:

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

Nu kan een taak op je site handelen — de werknemer voert api_request-aanroepen uit tegen je 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 — laat je app een werknemer activeren

Maak een webhook-verbinding aan en bind deze (inkomend):

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

Stuur vanuit je app een ondertekend event via POST wanneer er iets gebeurt — het wordt een taak:

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 — de volledige helpdesk-loop

Bind één supportwerknemer aan beide verbindingen (gebruik purpose: "BOTH", of bind de webhook als INBOUND en de Generic API als OUTBOUND). Een webhook voor een nieuw ticket maakt een taak aan → de werknemer concipieert een antwoord → en plaatst het antwoord terug in je helpdesk met een api_request-aanroep. Met goedkeuringen aan beoordeel je elk antwoord voordat het wordt verstuurd; met automatisch uitvoeren loopt het onbemand.

Zelfde patroon, elke app

Dezelfde twee bouwstenen koppelen een CMS, een CRM, een intern beheerpaneel of elke HTTP-API. Beperk de verbinding tot alleen de hosts en gegevens die de werknemer nodig heeft.

Referentie

Zie de SDK-pagina voor alle integrations.*-methoden, of de API-referentie voor POST /v1/integrations/connections.