Detailed Webhook Guide

Introduction

Webhooks are HTTPS POST requests sent from Cyberdesk to your service when events happen (e.g., a workflow run completes). They eliminate polling and let you react in real-time. The high-level steps:

Activate Webhooks in the Dashboard (creates a Svix Application for your org).
Add an endpoint URL and subscribe to run_complete.
Implement your endpoint to verify signatures and process events.
Test and monitor via the embedded Webhooks portal.

Events and Event Types

Cyberdesk webhooks are organized by event types (e.g., run_complete). You can browse the full, always-up-to-date list and their schemas in the Event Catalog inside the Webhooks portal. As of today, run_complete is the most commonly used type and fires when a workflow run reaches a terminal state (success, error, task_failed, or cancelled). Its payload includes the full Run object (see API reference for RunResponse).

Adding an Endpoint

Go to Dashboard → Webhooks.
Click “Add Endpoint” and enter your publicly reachable HTTPS URL.
Select the run_complete event type (or accept all for initial testing).
Copy the generated endpoint signing secret (whsec_...).

Keep separate endpoints/secrets for each environment (dev, staging, prod).

Testing Endpoints

Use the “Testing” tools in the Webhooks portal to send example events to your endpoint. Inspect payloads, responses, and message attempts under Logs/Activity. You can replay messages individually or recover all failed messages since a timestamp.

We’re building a managed Webhooks SDK with built‑in verification and typing. If you want this prioritized, please let the team know.

Verifying Signatures

Always verify signatures to ensure messages originate from Cyberdesk. We use Svix headers and signing format. Headers sent with every webhook:

svix-id – unique message id (use for idempotency)
svix-timestamp – Unix timestamp
svix-signature – signature over the raw request body

Install dependencies

TypeScript / Node
Python

npm install cyberdesk svix
# or
yarn add cyberdesk svix
# or
pnpm add cyberdesk svix

pip install cyberdesk svix
# or
poetry add cyberdesk svix
# or
pipenv install cyberdesk svix

Endpoint handlers

TypeScript / Node
Python

import express from "express";
import { Webhook, WebhookVerificationError } from "svix";
import { createCyberdeskClient } from "cyberdesk";
import type { RunCompletedEvent, RunResponse } from "cyberdesk";

const app = express();
app.use(express.raw({ type: "application/json" }));

function assertRunCompletedEvent(x: unknown): asserts x is RunCompletedEvent {
  if (!x || (x as any).event_type !== "run_complete" || !(x as any).run) {
    throw new Error("Invalid run_complete payload");
  }
}

app.post("/webhooks/cyberdesk", (req, res) => {
  const secret = process.env.SVIX_WEBHOOK_SECRET!;
  const wh = new Webhook(secret);
  const headers = {
    "svix-id": req.header("svix-id")!,
    "svix-timestamp": req.header("svix-timestamp")!,
    "svix-signature": req.header("svix-signature")!,
  };
  try {
    const payload = wh.verify(req.body, headers);
    assertRunCompletedEvent(payload);
    const run: RunResponse = payload.run; // fully typed
    // process run
    res.status(200).end();
  } catch (err) {
    if (err instanceof WebhookVerificationError) return res.status(400).end();
    res.status(500).end();
  }
});

from fastapi import FastAPI, Request, HTTPException
from svix.webhooks import Webhook, WebhookVerificationError
from openapi_client.cyberdesk_cloud_client.models.run_completed_event import RunCompletedEvent
from openapi_client.cyberdesk_cloud_client.models.run_response import RunResponse
from typing import cast
import os

app = FastAPI()

@app.post("/webhooks/cyberdesk")
async def cyberdesk_webhook(request: Request):
    secret = os.environ["SVIX_WEBHOOK_SECRET"]
    wh = Webhook(secret)
    payload = await request.body()
    headers = {
        "svix-id": request.headers.get("svix-id"),
        "svix-timestamp": request.headers.get("svix-timestamp"),
        "svix-signature": request.headers.get("svix-signature"),
    }
    try:
        data = wh.verify(payload, headers)
        evt = RunCompletedEvent.from_dict(data)
        run: RunResponse = cast(RunResponse, evt.run)
        # process run
        return {"ok": True}
    except WebhookVerificationError:
        raise HTTPException(status_code=400, detail="Invalid signature")

Verify against the exact raw request body. Do not re-stringify JSON before verification.

Retry Mechanism

Cyberdesk (via Svix) retries failed deliveries using exponential backoff:

Immediately
5 seconds
5 minutes
30 minutes
2 hours
5 hours
10 hours
10 hours

A response with HTTP 2xx is considered success. Avoid long processing in the webhook handler—enqueue work and return 200 quickly to prevent timeouts. Manual retries: from the portal you can resend single messages or recover all failed messages since a given time.

Troubleshooting & Failure Recovery

Common pitfalls:

Not using raw body for signature verification
Using the wrong endpoint secret (each endpoint has its own secret)
Returning non-2xx status for successful processing
Handler timeouts (do heavy work asynchronously)

Failure recovery:

Re-enable disabled endpoints in the portal
Replay failed messages individually or recover all since a timestamp

Using run_complete Data

run_complete includes the full RunResponse. Useful patterns:

Trigger the next workflow in your pipeline
Update your job table with run.status and output_data
Persist output_attachment_ids and fetch/download files as needed
Correlate input_values to your original request (e.g., patient_id)
Understand sensitive inputs: plaintext secrets are never included in the payload. run.sensitive_input_aliases maps each sensitive input key (for example, password) to the secure secret identifier used during execution, so you can audit which sensitive variables were referenced without exposing their values.

Example: TypeScript handler

import { createCyberdeskClient } from "cyberdesk";
import type { RunCompletedEvent, RunResponse } from "cyberdesk";

if (payload.event_type === "run_complete") {
  const run: RunResponse = (payload as RunCompletedEvent).run;
  await db.runs.upsert({ id: run.id, status: run.status, output: run.output_data });
  // kick off a follow-up Cyberdesk run
  const client = createCyberdeskClient(process.env.CYBERDESK_API_KEY!);
  await client.runs.create({ workflow_id: process.env.NEXT_WORKFLOW_ID! });
  if (run.output_attachment_ids?.length) {
    // display download links using Cyberdesk attachment APIs
  }
}

Example: Python handler

import os
from cyberdesk import CyberdeskClient, RunCreate
from openapi_client.cyberdesk_cloud_client.models.run_completed_event import RunCompletedEvent
from openapi_client.cyberdesk_cloud_client.models.run_response import RunResponse
from typing import cast

evt = RunCompletedEvent.from_dict(data)
run: RunResponse = cast(RunResponse, evt.run)
save_status(run.id, run.status, run.output_data)
client = CyberdeskClient(os.environ["CYBERDESK_API_KEY"])
client.runs.create_sync(RunCreate(workflow_id=os.environ["NEXT_WORKFLOW_ID"]))

React to Post-run Check failures

run_complete is the best place to react to Post-run Checks, because the event fires only after those checks finish. The result data lives on run.post_run_checks. Important details:

run.post_run_checks is an array, not an object keyed by name
each item includes name, status, error_message, messages, and matched_filenames
if you want to access a specific check by name, keep names stable and unique in the workflow editor

TypeScript / Node
Python

function getFailedPostRunChecks(run: RunResponse) {
  return (run.post_run_checks ?? []).filter((check) => check.status !== "success");
}

function getCheckByName(run: RunResponse, name: string) {
  return (run.post_run_checks ?? []).find((check) => check.name === name);
}

app.post("/webhooks/cyberdesk", (req, res) => {
  const secret = process.env.SVIX_WEBHOOK_SECRET!;
  const wh = new Webhook(secret);
  const headers = {
    "svix-id": req.header("svix-id")!,
    "svix-timestamp": req.header("svix-timestamp")!,
    "svix-signature": req.header("svix-signature")!,
  };

  try {
    const payload = wh.verify(req.body, headers);
    assertRunCompletedEvent(payload);
    const run: RunResponse = payload.run;

    const failedChecks = getFailedPostRunChecks(run);
    const invoiceCheck = getCheckByName(run, "Invoice PDF exists");

    if (failedChecks.length > 0) {
      console.log("failed checks:", failedChecks.map((check) => ({
        name: check.name,
        status: check.status,
        error: check.error_message,
        messages: check.messages,
        matched: check.matched_filenames,
      })));
    }

    if (invoiceCheck && invoiceCheck.status !== "success") {
      console.log("invoice check did not pass:", invoiceCheck);
    }

    res.status(200).json({ ok: true });
  } catch (err) {
    res.status(400).json({ error: "Invalid signature" });
  }
});

def get_failed_post_run_checks(run: RunResponse):
    return [check for check in (run.post_run_checks or []) if getattr(check.status, "value", check.status) != "success"]

def get_check_by_name(run: RunResponse, name: str):
    return next((check for check in (run.post_run_checks or []) if check.name == name), None)


@app.post("/webhooks/cyberdesk")
async def cyberdesk_webhook(request: Request):
    secret = os.environ["SVIX_WEBHOOK_SECRET"]
    wh = Webhook(secret)

    payload = await request.body()
    headers = {
        "svix-id": request.headers.get("svix-id"),
        "svix-timestamp": request.headers.get("svix-timestamp"),
        "svix-signature": request.headers.get("svix-signature"),
    }

    try:
        data = wh.verify(payload, headers)
        evt = RunCompletedEvent.from_dict(data)
        run: RunResponse = cast(RunResponse, evt.run)

        failed_checks = get_failed_post_run_checks(run)
        invoice_check = get_check_by_name(run, "Invoice PDF exists")

        if failed_checks:
            print([
                {
                    "name": check.name,
                    "status": getattr(check.status, "value", check.status),
                    "error": check.error_message,
                    "messages": check.messages,
                    "matched": check.matched_filenames,
                }
                for check in failed_checks
            ])

        if invoice_check and getattr(invoice_check.status, "value", invoice_check.status) != "success":
            print("invoice check did not pass", invoice_check)

        return {"ok": True}
    except WebhookVerificationError:
        raise HTTPException(status_code=400, detail="Invalid signature")

Advanced example: dynamic workflow chain webhook

Some production integrations build the entire Cyberdesk chain up front, but the steps included in that chain depend on the initial request. For example, a charge-entry integration might always run an encounter setup workflow, skip remove/update/add workflows when their input arrays are empty, and always finish with a finalization workflow. In this pattern:

Create the chain with client.runs.chain(...) from your normal POST endpoint.
Store the returned run_ids in your database with their step order.
In your run_complete webhook, branch on every terminal status.
Treat non-success statuses before the final step as early chain stops; later runs may never emit webhooks.
When the final run has release_session_after: true, clean up any local locks or resources tied to that Cyberdesk session.

Python / FastAPI
Node.js / Express

import os
from typing import Any, cast

from cyberdesk import CyberdeskClient
from openapi_client.cyberdesk_cloud_client.models.workflow_chain_create import (
    WorkflowChainCreate,
)
from fastapi import BackgroundTasks, FastAPI, HTTPException, Request
from openapi_client.cyberdesk_cloud_client.models.run_completed_event import (
    RunCompletedEvent,
)
from openapi_client.cyberdesk_cloud_client.models.run_response import RunResponse
from svix.webhooks import Webhook, WebhookVerificationError

app = FastAPI()
client = CyberdeskClient(os.environ["CYBERDESK_API_KEY"])

# Replace this with durable database tables in production.
chains_by_run_id: dict[str, dict[str, Any]] = {}
processed_messages: set[str] = set()


def build_steps(batch: dict[str, Any]) -> list[dict[str, Any]]:
    steps = [
        {
            "workflow_id": os.environ["WORKFLOW_1_ID"],
            "session_alias": "encounter",
            "inputs": {
                "FIN": batch["FIN"],
                "icd_codes": batch["icd_codes"],
                "notes": batch["notes"],
            },
        }
    ]

    if batch.get("charges_to_remove"):
        steps.append({
            "workflow_id": os.environ["WORKFLOW_2_ID"],
            "session_alias": "remove_charges",
            "inputs": {"charges_to_remove": batch["charges_to_remove"]},
        })

    if batch.get("charges_to_update"):
        steps.append({
            "workflow_id": os.environ["WORKFLOW_3_ID"],
            "session_alias": "update_charges",
            "inputs": {"charges_to_update": batch["charges_to_update"]},
        })

    if batch.get("charges_to_add"):
        steps.append({
            "workflow_id": os.environ["WORKFLOW_4_ID"],
            "session_alias": "add_charges",
            "inputs": {"charges_to_add": batch["charges_to_add"]},
        })

    steps.append({
        "workflow_id": os.environ["WORKFLOW_5_ID"],
        "session_alias": "finalize",
        "inputs": {},
    })
    return steps


@app.post("/charge-batches")
def start_charge_batch(batch: dict[str, Any]):
    steps = build_steps(batch)
    chain = WorkflowChainCreate.from_dict({
        "steps": steps,
        "keep_session_after_completion": False,
    })

    response = client.runs.chain_sync(chain)
    if response.error or response.data is None:
        raise HTTPException(status_code=502, detail=str(response.error))

    run_ids = response.data.run_ids
    for index, run_id in enumerate(run_ids):
        chains_by_run_id[run_id] = {
            "session_id": response.data.session_id,
            "step_number": index + 1,
            "total_steps": len(run_ids),
            "workflow_id": steps[index]["workflow_id"],
        }

    return {
        "session_id": response.data.session_id,
        "run_ids": run_ids,
        "included_steps": [step["session_alias"] for step in steps],
    }


async def handle_run_terminal(run: RunResponse) -> None:
    record = chains_by_run_id.get(str(run.id))
    if not record:
        return

    is_final_step = record["step_number"] == record["total_steps"]

    if not is_final_step and run.status != "success":
        # PLACEHOLDER: Notify the client, retry the chain, or create a human
        # review task. Later steps may never run after this early stop.
        await mark_chain_failed(record, run.status, run.error)
        return

    if is_final_step:
        if run.status == "success":
            # PLACEHOLDER: Mark the full batch complete.
            await mark_chain_complete(record)
        elif run.status == "cancelled":
            # PLACEHOLDER: Mark finalization cancelled after earlier steps.
            await mark_chain_cancelled(record)
        else:
            # PLACEHOLDER: Handle finalization failure after prior mutations.
            await mark_chain_failed(record, run.status, run.error)

        if run.release_session_after:
            # PLACEHOLDER: Clear local locks/resources for this session.
            await cleanup_session(record["session_id"])
        return

    # PLACEHOLDER: Persist intermediate step success and wait for next webhook.
    await mark_step_success(record, run.output_data)


async def mark_chain_complete(record: dict[str, Any]) -> None: ...
async def mark_chain_cancelled(record: dict[str, Any]) -> None: ...
async def mark_chain_failed(
    record: dict[str, Any], status: str, error: Any
) -> None: ...
async def mark_step_success(record: dict[str, Any], output_data: Any) -> None: ...
async def cleanup_session(session_id: str) -> None: ...


@app.post("/webhooks/cyberdesk")
async def cyberdesk_webhook(request: Request, background_tasks: BackgroundTasks):
    raw_body = await request.body()
    message_id = request.headers.get("svix-id")
    headers = {
        "svix-id": message_id,
        "svix-timestamp": request.headers.get("svix-timestamp"),
        "svix-signature": request.headers.get("svix-signature"),
    }

    try:
        data = Webhook(os.environ["SVIX_WEBHOOK_SECRET"]).verify(raw_body, headers)
    except WebhookVerificationError:
        raise HTTPException(status_code=400, detail="Invalid signature")

    if message_id in processed_messages:
        return {"ok": True, "duplicate": True}
    if message_id:
        processed_messages.add(message_id)

    evt = RunCompletedEvent.from_dict(data)
    run: RunResponse = cast(RunResponse, evt.run)
    background_tasks.add_task(handle_run_terminal, run)
    return {"ok": True}

import express from "express";
import { Webhook, WebhookVerificationError } from "svix";
import { createCyberdeskClient } from "cyberdesk";
import type { RunCompletedEvent, RunResponse, WorkflowChainCreate } from "cyberdesk";

const app = express();
const rawJson = express.raw({ type: "application/json" });
const jsonBody = express.json();

const client = createCyberdeskClient(process.env.CYBERDESK_API_KEY!);

// Replace these with durable database tables in production.
const chainsByRunId = new Map<string, {
  sessionId: string;
  stepNumber: number;
  totalSteps: number;
  workflowId: string;
}>();
const processedMessages = new Set<string>();

function assertRunCompletedEvent(x: unknown): asserts x is RunCompletedEvent {
  if (!x || (x as any).event_type !== "run_complete" || !(x as any).run) {
    throw new Error("Invalid run_complete payload");
  }
}

function buildSteps(batch: any): WorkflowChainCreate["steps"] {
  const steps: WorkflowChainCreate["steps"] = [
    {
      workflow_id: process.env.WORKFLOW_1_ID!,
      session_alias: "encounter",
      inputs: {
        FIN: batch.FIN,
        icd_codes: batch.icd_codes,
        notes: batch.notes,
      },
    },
  ];

  if (batch.charges_to_remove?.length) {
    steps.push({
      workflow_id: process.env.WORKFLOW_2_ID!,
      session_alias: "remove_charges",
      inputs: { charges_to_remove: batch.charges_to_remove },
    });
  }

  if (batch.charges_to_update?.length) {
    steps.push({
      workflow_id: process.env.WORKFLOW_3_ID!,
      session_alias: "update_charges",
      inputs: { charges_to_update: batch.charges_to_update },
    });
  }

  if (batch.charges_to_add?.length) {
    steps.push({
      workflow_id: process.env.WORKFLOW_4_ID!,
      session_alias: "add_charges",
      inputs: { charges_to_add: batch.charges_to_add },
    });
  }

  steps.push({
    workflow_id: process.env.WORKFLOW_5_ID!,
    session_alias: "finalize",
    inputs: {},
  });
  return steps;
}

app.post("/charge-batches", jsonBody, async (req, res, next) => {
  try {
    const steps = buildSteps(req.body);
    const { data, error } = await client.runs.chain({
      steps,
      keep_session_after_completion: false,
    });
    if (error || !data) throw new Error(String(error));

    data.run_ids.forEach((runId, index) => {
      chainsByRunId.set(runId, {
        sessionId: data.session_id,
        stepNumber: index + 1,
        totalSteps: data.run_ids.length,
        workflowId: steps[index].workflow_id,
      });
    });

    res.json({
      session_id: data.session_id,
      run_ids: data.run_ids,
      included_steps: steps.map((step) => step.session_alias),
    });
  } catch (err) {
    next(err);
  }
});

async function handleRunTerminal(run: RunResponse) {
  const record = chainsByRunId.get(run.id);
  if (!record) return;

  const isFinalStep = record.stepNumber === record.totalSteps;

  if (!isFinalStep && run.status !== "success") {
    // PLACEHOLDER: Notify the client, retry the chain, or create a human
    // review task. Later steps may never run after this early stop.
    await markChainFailed(record, run.status, run.error);
    return;
  }

  if (isFinalStep) {
    if (run.status === "success") {
      // PLACEHOLDER: Mark the full batch complete.
      await markChainComplete(record);
    } else if (run.status === "cancelled") {
      // PLACEHOLDER: Mark finalization cancelled after earlier steps.
      await markChainCancelled(record);
    } else {
      // PLACEHOLDER: Handle finalization failure after prior mutations.
      await markChainFailed(record, run.status, run.error);
    }

    if (run.release_session_after) {
      // PLACEHOLDER: Clear local locks/resources for this session.
      await cleanupSession(record.sessionId);
    }
    return;
  }

  // PLACEHOLDER: Persist intermediate step success and wait for next webhook.
  await markStepSuccess(record, run.output_data);
}

async function markChainComplete(record: unknown) {}
async function markChainCancelled(record: unknown) {}
async function markChainFailed(record: unknown, status: string, error: unknown) {}
async function markStepSuccess(record: unknown, outputData: unknown) {}
async function cleanupSession(sessionId: string) {}

app.post("/webhooks/cyberdesk", rawJson, async (req, res) => {
  const messageId = req.header("svix-id");
  const headers = {
    "svix-id": messageId!,
    "svix-timestamp": req.header("svix-timestamp")!,
    "svix-signature": req.header("svix-signature")!,
  };

  try {
    const payload = new Webhook(process.env.SVIX_WEBHOOK_SECRET!).verify(req.body, headers);
    assertRunCompletedEvent(payload);

    if (messageId && processedMessages.has(messageId)) {
      return res.json({ ok: true, duplicate: true });
    }
    if (messageId) processedMessages.add(messageId);

    await handleRunTerminal(payload.run);
    res.json({ ok: true });
  } catch (err) {
    if (err instanceof WebhookVerificationError) return res.status(400).end();
    res.status(500).end();
  }
});

Idempotency

Deduplicate using svix-id (header) or event_id (payload). Store processed ids and ignore duplicates.

Finding webhooks by run ID

In the Svix dashboard, you can search for webhooks by their message ID. For most runs, the message ID equals the run ID, making it easy to find the webhook for a specific run.

Retried runs: If you retry a run (same run_id), the second webhook will have a timestamped message ID (e.g., abc123..._1702310400000) to ensure uniqueness. The first webhook for any run will always use just the run ID.

Security Checklist

Verify signatures and timestamp
Use HTTPS only
Rotate secrets when needed
Return 2xx promptly; process work asynchronously

Payload Transformations

If your webhook payloads are too large or you need to reshape the data before it reaches your endpoint, you can use transformations to modify the payload server-side. This is particularly useful for:

Removing the run.run_message_history field, which can be very large
Extracting only the fields your system needs
Reformatting data to match your expected schema

See Webhook Transformations for setup instructions and examples.

Getting started

SDK Guides

Cyberdriver

Workflow Prompting

Webhooks

Concepts

Additional Details

Introduction

Events and Event Types

Adding an Endpoint

Testing Endpoints

Verifying Signatures

Install dependencies

Endpoint handlers

Retry Mechanism

Troubleshooting & Failure Recovery

Using run_complete Data

Example: TypeScript handler

Example: Python handler

React to Post-run Check failures

Advanced example: dynamic workflow chain webhook

Idempotency

Finding webhooks by run ID

Security Checklist

Payload Transformations

See Also

Getting started

SDK Guides

Cyberdriver

Workflow Prompting

Webhooks

Concepts

Additional Details

Documentation Index

​Introduction

​Events and Event Types

​Adding an Endpoint

​Testing Endpoints

​Verifying Signatures

​Install dependencies

​Endpoint handlers

​Retry Mechanism

​Troubleshooting & Failure Recovery

​Using run_complete Data

​Example: TypeScript handler

​Example: Python handler

​React to Post-run Check failures

​Advanced example: dynamic workflow chain webhook

​Idempotency

​Finding webhooks by run ID

​Security Checklist

​Payload Transformations

​See Also

Introduction

Events and Event Types

Adding an Endpoint

Testing Endpoints

Verifying Signatures

Install dependencies

Endpoint handlers

Retry Mechanism

Troubleshooting & Failure Recovery

Using run_complete Data

Example: TypeScript handler

Example: Python handler

React to Post-run Check failures

Advanced example: dynamic workflow chain webhook

Idempotency

Finding webhooks by run ID

Security Checklist

Payload Transformations

See Also