> ## 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.

# Legacy Using Webhooks

> Trigger workflows from external events and receive results without polling.

This page documents webhooks for the original routes, which keep working. For new integrations, see [Using Webhooks](https://docs.sixtyfour.ai/guides/using-webhooks.md).

| Direction | Use it to | Reference |
| - | - | - |
| Incoming | Start a workflow when a form, CRM or app fires an event | [Incoming Webhooks](https://docs.sixtyfour.ai/api-reference/webhooks/incoming.md) |
| Outgoing | Receive async job results or workflow output at your URL | [Outgoing Webhooks](https://docs.sixtyfour.ai/api-reference/webhooks/outgoing.md) |
| Signing | Verify that deliveries come from Sixtyfour | [Signing Secrets](https://docs.sixtyfour.ai/api-reference/webhooks/signing-secrets.md) |

## Trigger a workflow from an external event

Build a workflow whose first block is a `webhook` source, then POST the event data to `/workflows/run` with your API key:

```bash theme={null}
curl -X POST "https://api.sixtyfour.ai/workflows/run?workflow_id=WORKFLOW_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_payload": [
      { "name": "Roham", "company": "Sixtyfour" }
    ]
  }'
```

Each object in `webhook_payload` becomes a row. Payload rules and the response are in [Incoming Webhooks](https://docs.sixtyfour.ai/api-reference/webhooks/incoming.md).

## Receive async results at your URL

Add `webhook_url` to any async endpoint. Sixtyfour POSTs the result when the job completes.

```bash cURL theme={null}
curl -X POST "https://api.sixtyfour.ai/find-email-async" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lead": { "name": "Roham", "company": "Sixtyfour" },
    "webhook_url": "https://your-server.com/webhooks/sixtyfour"
  }'
```

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

response = requests.post(
    "https://api.sixtyfour.ai/find-email-async",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "lead": {"name": "Roham", "company": "Sixtyfour"},
        "webhook_url": "https://your-server.com/webhooks/sixtyfour",
    },
)
task_id = response.json()["task_id"]
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.sixtyfour.ai/find-email-async", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    lead: { name: "Roham", company: "Sixtyfour" },
    webhook_url: "https://your-server.com/webhooks/sixtyfour",
  }),
});
const { task_id } = await response.json();
```

Store the `task_id` so you can match the callback and fall back to `GET /job-status/{task_id}` if no callback arrives. The supported endpoints and payload fields are in [Outgoing Webhooks](https://docs.sixtyfour.ai/api-reference/legacy/outgoing-webhooks.md#async-job-webhooks).

To post workflow output instead, end the workflow with an `outgoing_webhook` block. See [Workflow outgoing\_webhook block](https://docs.sixtyfour.ai/api-reference/webhooks/outgoing.md#workflow-webhooks).

## Handle deliveries

A receiver verifies the signature, acknowledges fast and processes later:

```python theme={null}
from flask import Flask, request

app = Flask(__name__)
seen_deliveries = set()


def delivery_key(event: dict) -> str:
    if "task_id" in event:  # async-job callback
        return f"task:{event['task_id']}"
    if event.get("event") == "outgoing_webhook.completed":  # workflow block
        return f"run:{event['run_id']}:{event['previous_block_id']}"
    return f"{event['type']}:{event.get('event_group_id') or event['run_id']}"  # monitor


@app.post("/webhooks/sixtyfour")
def sixtyfour_webhook():
    raw_body = request.get_data()
    if not verify(raw_body, request.headers.get("Sixtyfour-Signature", ""), SECRET):
        return "", 401

    event = request.get_json()
    key = delivery_key(event)
    if key in seen_deliveries:
        return "", 200

    enqueue(event)  # process outside the request
    seen_deliveries.add(key)  # only after the event is queued
    return "", 200
```

`verify` is the function in [Signing Secrets](https://docs.sixtyfour.ai/api-reference/webhooks/signing-secrets.md#verify-signatures). Verify against the raw body before parsing JSON. Use a persistent store for `seen_deliveries` in production.

`delivery_key` dedupes on the job or run, not `event_id`: monitor notifications carry no `event_id`, and Sixtyfour can deliver the same result again with a new `event_id`.

## Test locally

Sixtyfour only delivers to public hosts, and async-job callbacks and test deliveries require HTTPS. Expose your local server through a tunnel such as ngrok or Cloudflare Tunnel and use the tunnel's HTTPS URL as `webhook_url`.

## Test deliveries

Send a sample delivery to your receiver to check its signature verification and parsing before a real job runs. A test delivery runs no job and uses no credits.

`GET /webhooks/test-events` lists the samples. Each entry has a `type`, a `description`, and an `example` payload. Add `?type=find_email` to get that one example payload on its own.

`POST /webhooks/test-events` sends one sample to your URL with the same signing and retries as a real delivery:

| Field | Required | Description |
| - | - | - |
| `event` | Yes | A `type` from `GET /webhooks/test-events`. |
| `url` | Yes | Your receiver's public `https://` URL. |
| `signing` | No | `auto` (default) signs the delivery when your organization has a signing secret, like a real delivery. `required` refuses to send when there is no active signing secret. |

```bash cURL theme={null}
curl -X POST "https://api.sixtyfour.ai/webhooks/test-events" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "find_email",
    "url": "https://your-server.com/webhooks/sixtyfour",
    "signing": "required"
  }'
```

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

response = requests.post(
    "https://api.sixtyfour.ai/webhooks/test-events",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "event": "find_email",
        "url": "https://your-server.com/webhooks/sixtyfour",
        "signing": "required",
    },
    timeout=120,
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.sixtyfour.ai/webhooks/test-events", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    event: "find_email",
    url: "https://your-server.com/webhooks/sixtyfour",
    signing: "required",
  }),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

```json theme={null}
{
  "id": "21b3e340-e326-4c01-9a42-7dc426ec4481",
  "delivered": true,
  "status_code": 200,
  "attempts": 1
}
```

`delivered` is `true` only when your receiver returned `2xx`. `status_code` is the last attempt's HTTP status, or `null` when no response arrived. The call waits for every retry and can take up to 100 seconds. Each call sends a new event, so don't retry it automatically.

Test deliveries carry these headers on top of the [delivery headers](https://docs.sixtyfour.ai/api-reference/webhooks/outgoing.md#headers):

| Header | Value |
| - | - |
| `Sixtyfour-Test` | `true` |
| `Sixtyfour-Test-Run-Id` | The `id` from the response. The sample payload uses it as its event or task ID. |
| `Sixtyfour-Test-Case` | The `event` you sent |

The catalog also lists other samples. These `type` values match deliveries Sixtyfour sends:

| `type` | Matches |
| - | - |
| `find_email`, `find_phone`, `reverse_enrichment` | Find Email, Find Phone, and Reverse Email or Reverse Phone callbacks |
| `lead_enrichment`, `lead_enrichment_xhigh` | People Intelligence callbacks. The `xhigh` sample adds `investigation` |
| `company_enrichment` | Company Intelligence callbacks |
| `outgoing_webhook` | The workflow `outgoing_webhook` block. Its download links are `null` |
| `monitor.field.changed`, `monitor.execution.completed`, `monitor.execution.failed`, `monitor.run.completed` | [Monitor notifications](https://docs.sixtyfour.ai/api-reference/monitors/monitor-notifications.md) |

Test deliveries are [rate limited](https://docs.sixtyfour.ai/api-reference/rate-limits.md#webhooks). For error responses, see [Handling Errors](https://docs.sixtyfour.ai/api-reference/errors.md).

## Production checklist

* Create a signing secret under **Webhooks** in **Settings** and reject unsigned deliveries.
* Return `2xx` within 10 seconds, including for events you ignore.
* Dedupe on the job or run, as `delivery_key` does above.
* Poll `GET /job-status/{task_id}` when a callback is late. Failed jobs send no callback.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.