Using Webhooks - Sixtyfour AI Documentation

Webhooks connect Sixtyfour to your systems in both directions: external events start workflows, and Sixtyfour posts results to your server when work completes.

Direction	Use it to	Reference
Incoming	Start a workflow when a form, CRM or app fires an event	Incoming Webhooks
Outgoing	Receive async job results or workflow output at your URL	Outgoing Webhooks
Signing	Verify that deliveries come from Sixtyfour	Signing Secrets

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:

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": "Jane Smith", "company": "Northgate Labs" }
    ]
  }'

Each object in webhook_payload becomes a row. Payload rules and the response are in Incoming Webhooks.

Receive async results at your URL

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

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": "Jane Smith", "company": "Northgate Labs" },
    "webhook_url": "https://your-server.com/webhooks/sixtyfour"
  }'

import requests

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

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: "Jane Smith", company: "Northgate Labs" },
    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. To post workflow output instead, end the workflow with an outgoing_webhook block. See Workflow outgoing_webhook block.

Handle deliveries

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

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

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"
  }'

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())

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());

{
  "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:

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
`qa_agent`	QA Agent 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

Test deliveries are rate limited. For error responses, see Handling Errors.

Production checklist

Create a signing secret in Settings → Webhooks 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.

​Trigger a workflow from an external event

​Receive async results at your URL

​Handle deliveries

​Test locally

​Test deliveries

​Production checklist