cloudforbots-com Webhooks API

openapi: 3.2.0
info:
  title: Cloud for Bots Webhooks API
  version: 1.0.0
  description: 'One API for every Cloud for Bots tool: loop detection, run memory (checkpoint/resume), run budgets, approval rules and scheduled wake-ups for AI agents. **Auth:** `Authorization: Bearer `. Any one of your keys works for every tool. Free keys: https://cloudforbots.com/offer


    **Retries:** read actions retry automatically on 502/503/504. Send `Idempotency-Key` to make writes safe to retry. **Limits:** 20 requests/second per key (429 + `Retry-After`). **Webhooks:** signed with `cfb-signature: t=,v1=`, where v1 = HMAC-SHA256(secret, t + "." + raw body). Retries: 1m, 5m, 30m, 2h, 6h. **MCP:** https://cloudforbots.com/mcp (Streamable HTTP). **Status:** https://cloudforbots.com/status


    **SDKs:** TypeScript/JS (types) · Python


    # Quickstart


    Get a free key at cloudforbots.com/offer (one email, keys show right away). Any one of your keys works for every tool. Keep it in an environment variable:


    ```bash

    export CLOUDFORBOTS_API_KEY=mb_your_key_here

    ```


    ## TypeScript / JavaScript


    No install needed: the SDK is one zero-dependency ES module (Node 18+, Deno, Bun, browsers). ```bash

    curl -o cloudforbots.mjs https://cloudforbots.com/sdk/cloudforbots.mjs

    curl -o cloudforbots.d.ts https://cloudforbots.com/sdk/cloudforbots.d.ts # types for TypeScript

    ```


    ```ts

    import { CloudForBots, CloudForBotsError } from "./cloudforbots.mjs";


    const cfb = new CloudForBots(); // reads CLOUDFORBOTS_API_KEY


    // 1. After each agent step, ask Loop Breaker if the run is stuck

    const step = await cfb.loop.checkStep({ run_id: "invoice-run-42", tool: "search_crm", args: { customer: 4471 }, error: "timeout after 30s" });

    if (step.halt) throw new Error("Loop detected: " + step.outcome);


    // 2. Save progress so a crashed run can resume

    await cfb.memory.saveCheckpoint({ run_id: "invoice-run-42", step: "invoice-312", state: { done: 312 } }, { idempotencyKey: "invoice-run-42:312" });

    const resume = await cfb.memory.resume({ run_id: "invoice-run-42" });


    // 3. Errors carry the HTTP status, type and request id

    try { await cfb.approve.checkAction({ action: "delete 40 customer records" }); }

    catch (e) { if (e instanceof CloudForBotsError) console.error(e.status, e.type, e.requestId); }

    ```


    ## Python


    Standard library only (Python 3.8+). ```bash

    curl -o cloudforbots.py https://cloudforbots.com/sdk/cloudforbots.py

    ```


    ```python

    from cloudforbots import CloudForBots, CloudForBotsError


    cfb = CloudForBots() # reads CLOUDFORBOTS_API_KEY


    step = cfb.loop.check_step(run_id="invoice-run-42", tool="search_crm", args={"customer": 4471}, error="timeout after 30s")

    if step.get("halt"):

    raise SystemExit("Loop detected: " + step["outcome"])


    cfb.memory.save_checkpoint(run_id="invoice-run-42", step="invoice-312", state={"done": 312}, idempotency_key="invoice-run-42:312")

    print(cfb.memory.resume(run_id="invoice-run-42"))


    try:

    cfb.approve.check_action(action="delete 40 customer records")

    except CloudForBotsError as e:

    print(e.status, e.type, e.request_id)

    ```


    ## Webhooks


    ```python

    from cloudforbots import verify_webhook

    # Flask example: raw bytes, exactly as received

    ok = verify_webhook(WEBHOOK_SECRET, request.headers["cfb-signature"], request.get_data())

    ```


    Register an endpoint with `cfb.webhooks_add("https://you.example/hook", ["loop.halted", "budget.stopped"])` (Python) or `cfb.webhooks.add(url, events)` (JS). The secret is returned once. Rotate it with `cfb.webhooks_rotate(url)`: the old secret keeps working for 24 hours, and during that window `cfb-signature` carries two `v1=` values (`verify_webhook` accepts either). See failed deliveries with `cfb.webhooks_deliveries("failed")` and resend one with `cfb.webhooks_redeliver(id)`. Events: `loop.halted`, `budget.stopped`, `approval.held`, `call.failed`, `key.cap_warning`, `key.cap_reached`, `key.expiring`, `key.expired`. ## MCP


    Point any MCP client at `https://cloudforbots.com/mcp` with header `Authorization: Bearer $CLOUDFORBOTS_API_KEY`.'
servers:
- url: https://cloudforbots.com
security:
- bearer: []
tags:
- name: Webhooks
paths:
  /api/v1/webhooks/deliveries:
    get:
      operationId: webhooks__deliveries
      tags:
      - Webhooks
      summary: 'Delivery log: last 50 deliveries with status, tries and response code'
      parameters:
      - name: filter
        in: query
        required: false
        schema:
          type: string
        description: failed, pending, delivered or an event name
      responses:
        '200':
          description: ok
  /api/v1/webhooks/redeliver/{id}:
    post:
      operationId: webhooks__redeliver
      tags:
      - Webhooks
      summary: Send a past delivery again (same payload, fresh signature, new delivery id).
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: ok
  /api/v1/webhooks/rotate:
    post:
      operationId: webhooks__rotate
      tags:
      - Webhooks
      summary: New signing secret for an endpoint
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              properties:
                url:
                  type: string
      description: The old secret stays valid 24h; during that window cfb-signature carries two v1= values, accept either.
      responses:
        '200':
          description: ok
  /api/v1/webhooks:
    get:
      operationId: webhooks__list
      tags:
      - Webhooks
      summary: List webhook endpoints and recent deliveries
      responses:
        '200':
          description: ok
    post:
      operationId: webhooks__add
      tags:
      - Webhooks
      summary: Add an endpoint (returns the signing secret once).
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              properties:
                url:
                  type: string
                  format: uri
                  pattern: ^https://
                events:
                  type: array
                  items:
                    type: string
                    enum:
                    - '*'
                    - loop.halted
                    - budget.stopped
                    - approval.held
                    - call.failed
                    - webhook.test
      responses:
        '200':
          description: ok
    delete:
      operationId: webhooks__remove
      tags:
      - Webhooks
      summary: Remove an endpoint
      parameters:
      - name: url
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ok
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer