> For the complete documentation index, see [llms.txt](https://docs.distro.so/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.distro.so/workflows/api-and-webhooks.md).

# API and webhooks

Start a workflow from your own backend or receive an event from another system. Keep credentials on the server, and give each real event a stable identity.

## Choose API or webhook

| Source               | Use it for                                                                     |
| -------------------- | ------------------------------------------------------------------------------ |
| **API call**         | Your backend chooses a published workflow and sends its declared input fields. |
| **Webhook received** | An external system posts a payload to the workflow's configured endpoint.      |

A webhook trigger and **Call Webhook** are different directions: the trigger receives an event; the action sends a request.

## Start through the API

Create a workflow with **API call** and configure **Inputs**. Publish it and turn it On.

Use an API token with workflow-start access in the intended workspace. Supply the workspace as `account_id`.

From your server, send:

```http
POST /api/v1/triggers/WORKFLOW_ID?account_id=WORKSPACE_ID
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Idempotency-Key: demo-request-123

{
  "input": {
    "email": "alex@example.com",
    "name": "Alex Example"
  },
  "attribution": {
    "utm_source": "email",
    "utm_campaign": "product-demo"
  }
}
```

Replace the placeholders with your deployment, workspace, workflow, token, and actual declared fields.

An accepted new event returns `201` with `run_id`. A repeat of the same accepted event returns the original result with `duplicate: true`. Reusing an identity with different data can return `409`.

Use the same idempotency key when retrying the same event. Use a new key for a genuinely new invocation. Keys accept 1–200 letters, numbers, underscores, dots, colons, or dashes.

## Read the result

Poll from your server with the same token:

```http
GET /api/v1/triggers/runs/RUN_ID?account_id=WORKSPACE_ID
Authorization: Bearer YOUR_API_TOKEN
```

Review `status` and `outcome`. An accepted event is not yet proof that the workflow's later actions succeeded.

Scheduling outcomes include session-specific information. A custom frontend needs a compatible credential handoff and expiry handling; redirecting to a raw `page_url` alone is insufficient. Use the supported form SDK for a ready-made website scheduling journey.

## Receive a webhook

Choose **Webhook received**, then open **Webhook setup**. Create the endpoint, select authentication, and use its generated request example.

Declare the payload schema and the **Lead email field** or **Company domain field** used to identify the lead. A nested value can use a path such as `contact.email`.

Use the sample-capture controls to inspect a real sample and apply its schema before publication. Protect the endpoint secret and review sample data before sharing it.

## Handle errors

A rejected call may indicate missing access, a paused workflow, invalid inputs, or unavailable workspace activation. Inspect the returned error and workflow Logs.

Do not place your workspace API token in an email link or public browser code. For websites, see [Form SDK](/forms/sdk.md).

## Complete API reference

Start with [Authentication and workspaces](/developers/authentication.md), [Start a workflow](/developers/start-workflow.md) and [Read progress and outcomes](/developers/workflow-progress.md). The run outcome exposes a scheduler mutation token, while receipt reads require a separate credential not exposed by that response. Use the supported form SDK for a complete visitor workflow scheduling handoff.

The separate [Scheduling-link API](/developers/scheduling-links.md) supports booking through existing personal/group links.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.distro.so/workflows/api-and-webhooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.