Skip to main content

Execute Component

Auth: X-Api-Key: ws_...

POST /v1/sdk/components

Submit a component for execution. Returns immediately with an execution record.

Request body​

{
  module: string;           // Component module name (e.g. "RANDOM_UUID")
  input: object;            // Component inputs — see Component Library for schema
  config: object;           // Component config — see Component Library for schema

  // Delivery options (all optional)
  attempts?: number;        // 1–3, default: 1
  waitForMs?: number;       // Wait up to N ms for inline result (max 15000)
  callbackUrl?: string;     // HTTPS webhook URL for async delivery
  callbackSecret?: string;  // HMAC-SHA256 signing key for webhook
  callbackHeaders?: Record<string, string>; // Custom headers on webhook request
}
Execution is asynchronous by default

Without waitForMs, this endpoint returns immediately with status: "CREATED". The component runs in the background. Use waitForMs for an inline result, subscribe to the SSE stream, or configure a callbackUrl for webhook delivery.

Response 200 — default (async)​

{
  "id": "3f7a1b2c-...",
  "module": "RANDOM_UUID",
  "status": "CREATED",
  "completed": false,
  "output": null,
  "error": null,
  "totalUsage": 0,
  "callback": {
    "url": null,
    "signed": false,
    "signatureAlgorithm": null,
    "headerNames": [],
    "lastAttemptAt": null,
    "deliveredAt": null,
    "attemptCount": 0,
    "lastError": null
  },
  "createdAt": "2026-04-20T10:00:00Z",
  "updatedAt": "2026-04-20T10:00:00Z"
}

Use id to poll GET /v1/sdk/components/executions/:id or subscribe to the SSE stream.

Response 200 — with waitForMs (may be COMPLETED)​

When waitForMs is set, the server waits up to that many milliseconds before responding. If the component finishes in time, status will be "COMPLETED" and output will be populated.

{
  "id": "3f7a1b2c-...",
  "module": "RANDOM_UUID",
  "status": "COMPLETED",
  "completed": true,
  "output": { "uuid": "a4c2e8f1-..." },
  "error": null,
  "totalUsage": 1,
  "callback": {
    "url": null,
    "signed": false,
    "signatureAlgorithm": null,
    "headerNames": [],
    "lastAttemptAt": null,
    "deliveredAt": null,
    "attemptCount": 0,
    "lastError": null
  },
  "createdAt": "2026-04-20T10:00:00Z",
  "updatedAt": "2026-04-20T10:00:01Z"
}

Example — wait for inline result​

Request signing required

All REST API calls require X-Sdk-Timestamp and X-Sdk-Signature headers in addition to the API key. See Authentication → for the signing implementation. The TypeScript SDK handles this automatically.

# Signing helper (Node.js) — run once to generate headers
node -e "
const { createPrivateKey, sign } = require('crypto');
const pk = createPrivateKey({ key: Buffer.from(process.env.WR_API_SECRET, 'base64'), format: 'der', type: 'pkcs8' });
const ts = Math.floor(Date.now()/1000);
const body = JSON.stringify({ module: 'RANDOM_UUID', input: {}, config: {}, waitForMs: 5000 });
const msg = 'POST|/v1/sdk/components|' + ts + '|' + body;
const sig = sign(null, Buffer.from(msg), pk).toString('base64');
console.log('Timestamp:', ts);
console.log('Signature:', sig);
"
curl -X POST https://api.whiterabbit.app/v1/sdk/components \
  -H "X-Api-Key: ws_..." \
  -H "X-Sdk-Timestamp: <timestamp>" \
  -H "X-Sdk-Signature: <signature>" \
  -H "Content-Type: application/json" \
  -d '{
    "module": "RANDOM_UUID",
    "input": {},
    "config": {},
    "waitForMs": 5000
  }'

Example — async with webhook​

curl -X POST https://api.whiterabbit.app/v1/sdk/components \
  -H "X-Api-Key: ws_..." \
  -H "X-Sdk-Timestamp: <timestamp>" \
  -H "X-Sdk-Signature: <signature>" \
  -H "Content-Type: application/json" \
  -d '{
    "module": "WAIT_FOR_EVM_TRANSACTION",
    "input": {
      "jsonRpcUrl": "https://eth-mainnet.g.alchemy.com/v2/KEY",
      "transactionHash": "0xabc123..."
    },
    "config": {},
    "callbackUrl": "https://your-app.com/webhooks/wr",
    "callbackSecret": "my-hmac-secret",
    "attempts": 2
  }'

See Webhooks → for signature verification and replay.