> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sixtyfour.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Incoming Webhooks

> Trigger workflows by POSTing data to Sixtyfour.

## Use Case

Send data into Sixtyfour from an external system to start a workflow run. Use incoming webhooks to wire CRMs, schedulers, internal tools, or any service that needs to kick off enrichment automatically — no manual upload required.

<Tip>
  An incoming webhook is a workflow whose first block is the **`webhook` source block**. POST a payload to `/workflows/run`, and that payload becomes the workflow's input dataset.
</Tip>

## Headers

| Name         | Type   | Required | Description            |
| ------------ | ------ | -------- | ---------------------- |
| x-api-key    | string | Yes      | Your Sixtyfour API key |
| Content-Type | string | Yes      | `application/json`     |

<Note>Incoming webhooks require **API key authentication**. JWT (dashboard session) authentication is rejected when sending a webhook payload.</Note>

## Error Responses

For error response shapes (400, 422, etc.), see [Handling Errors](/api-reference/errors).

## Configure the webhook block

The `webhook` block is configured inside the workflow editor. It defines the shape of the data your workflow expects.

| Spec field       | Type          | Required    | Description                                                                                                                  |
| ---------------- | ------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `input_schema`   | object        | Recommended | Map of column name → field schema. Declares the columns the workflow expects so they can be referenced by downstream blocks. |
| `webhook_input`  | string (JSON) | No          | Default sample payload used when the workflow is run without an external POST (e.g. test runs in the editor).                |
| `dataframe_type` | string        | Yes         | `LEAD` or `COMPANY`. Determines which downstream blocks can consume the output.                                              |

Each row in your POSTed payload becomes one row in the workflow's input dataset. Columns not declared in `input_schema` are still passed through and surfaced as advisory columns to downstream blocks.

See the [Workflow Blocks reference](/api-reference/workflows/workflow-blocks) for where this fits in the block catalog.

## Trigger a workflow run

POST your payload to `/workflows/run` with the workflow ID as a query parameter.

```http theme={null}
POST https://api.sixtyfour.ai/workflows/run?workflow_id={workflow_id}
```

### Request Body

| Field             | Type            | Description                                                                                                                  |
| ----------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `webhook_payload` | array or object | Input data for the workflow. Can be a list of records (multi-row) or a single object (one row).                              |
| `specs_override`  | object          | Optional. Override specs of the source block. See the workflow editor's "Workflow API Reference" for block-specific options. |

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.sixtyfour.ai/workflows/run?workflow_id=wf_abc123" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "webhook_payload": [
        {
          "company_name": "Acme Corp",
          "website": "acme.com",
          "industry": "Technology"
        },
        {
          "company_name": "TechStart Inc",
          "website": "techstart.io",
          "industry": "Software"
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.sixtyfour.ai/workflows/run",
      headers={
          "x-api-key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      params={"workflow_id": "wf_abc123"},
      json={
          "webhook_payload": [
              {"company_name": "Acme Corp", "website": "acme.com"},
              {"company_name": "TechStart Inc", "website": "techstart.io"},
          ]
      },
  )
  job_id = response.json()["job_id"]
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.sixtyfour.ai/workflows/run?workflow_id=wf_abc123",
    {
      method: "POST",
      headers: {
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        webhook_payload: [
          { company_name: "Acme Corp", website: "acme.com" },
          { company_name: "TechStart Inc", website: "techstart.io" },
        ],
      }),
    }
  );
  const { job_id } = await response.json();
  ```
</CodeGroup>

### Response (200)

```json theme={null}
{
  "status": "queued",
  "workflow_id": "wf_abc123",
  "job_id": "run_xyz789",
  "cache_config": null
}
```

Use the returned `job_id` to track execution. See [Workflow Execution](/api-reference/workflows/workflows-execution) for status, results, and cancellation endpoints.

## Rules and constraints

* Source block must be `webhook`. Workflows whose source block is anything else cannot be triggered with `webhook_payload`.
* API key authentication only. JWT (dashboard session) auth is rejected when sending `webhook_payload`.
* `read_csv` source blocks are triggered with `specs_override.resource_handle_id` (from `/storage/csv/upload`), not `webhook_payload`. See [Workflow Execution](/api-reference/workflows/workflows-execution).
* Payloads missing required columns from `input_schema`, or malformed JSON, are rejected with a validation error.
* Workflows must have exactly one source block. The webhook block is consumed once per run.

## Receiving results

Incoming webhooks only handle the trigger. To receive workflow output back at your URL, add an `outgoing_webhook` block to the workflow — see [Outgoing Webhooks](/api-reference/webhooks/outgoing).

Alternatively, poll for completion and download results manually via the [Workflow Execution](/api-reference/workflows/workflows-execution) endpoints.