Webhook integration

Start a neuron from your own systems with a signed call, check its status, and send results to your own address.

Webhooks connect Neuron Workflows to your own systems in both directions. An inbound webhook lets your system start a neuron or an agent with a signed HTTP call. An outbound webhook, the API destination in a neuron's SEND tab, posts the neuron's result to your address after each run.

Start a neuron from your system

1. Open the neuron's START tab, choose Webhook, and copy the address shown under API webhook & keys. It ends in /api/webhook/receive/ followed by the neuron's ID.
2. Create a key with New key and copy its Key ID and Secret. See API keys.
3. From your system, send a POST to the address with a JSON body and two headers:
   • X-Api-Key: the key ID.
   • X-Webhook-Signature: the hex-encoded HMAC-SHA256 of the exact request body, using the key's secret.
4. The answer comes back right away (HTTP 201) with a requestId. The neuron runs in the background.

For an agent, use the Webhook URL in the agent's API Endpoint dialog in My Agents instead.

Request body

{
  "content": "Your input text here",
  "contentType": "text",
  "outputType": "text",
  "neuronId": "external-caller",
  "neuronName": "My App"
}

• content: the input for the neuron.
• contentType: the kind of input, such as text.
• outputType: the kind of result, text, image, audio or table.
• neuronId and neuronName: optional, to say which system sent the call.

Match the input to what the neuron's GET expects.

Sign the call

The signature covers the exact bytes you send. Sign the body as a string and send that same string.

const crypto = require("crypto");
const body = JSON.stringify(payload);
const signature = crypto
  .createHmac("sha256", apiSecret)
  .update(body)
  .digest("hex");
// send `body` with headers X-Api-Key: keyId, X-Webhook-Signature: signature

The first answer

{
  "status": "received",
  "requestId": "wrq_abc123…",
  "targetNeuronId": "neuron-id",
  "sourceNeuronId": "external-caller",
  "timestamp": "2026-01-15T10:30:00.000Z"
}

If the neuron has an input set to Ask when run, the run waits for your answer on the canvas; the reply to the webhook then has no output yet.

Check a call's status

Send a POST to the same address with /status added at the end, signed with the same key, and the requestId in the body:

{ "requestId": "wrq_abc123…" }

The answer gives the status, not the result:

{
  "requestId": "wrq_abc123…",
  "targetNeuronId": "neuron-id",
  "status": "completed",
  "updatedAt": "2026-01-15T10:30:05.000Z"
}

• queued: received, waiting to run.
• processing: the neuron is running.
• waiting: the neuron is paused and waiting for an answer from a person. Open the workflow to answer it; the run then continues.
• completed: the run finished.
• failed: the run ended with an error.
• timed_out: the run didn't finish within 1 minute. The run itself may still finish; only the status stops waiting.

To get the result itself, add an outbound webhook to the neuron (below), or send the result on with SEND › Email, Telegram or Document.

Send results to your address (outbound)

1. Open the neuron's SEND tab and choose API.
2. Type your address under Endpoint URL; adding it turns API on. It must start with https://, http:// or /. It is saved when you leave the field; clearing it turns API off.
3. After each run, the neuron sends a POST with a JSON body to your address:

{
  "neuronId": "neuron-id",
  "neuronName": "Summarise",
  "content": "The neuron's result",
  "contentType": "text",
  "timestamp": "2026-01-15T10:30:05.000Z",
  "outputType": "text"
}

Your address must be reachable from the internet; addresses on a private network are refused. A failed send isn't tried again.

Call one of your neurons from another

To have one neuron start another when it finishes, paste the second neuron's webhook address into the first neuron's SEND › API Endpoint URL. Neuron signs these calls itself; you don't need a key. Connections on the canvas do the same job without an address; see Connections.

Limits

• Status wait: a call's status turns timed_out after 1 minute.

Common problems

X-Api-Key header is required

The call has no X-Api-Key header. Add it with the key ID.

Invalid API key or signature

The key ID is wrong, the key is revoked or expired, or the signature doesn't match. Sign the exact string you send, with the key's secret, and send the signature as hex.

API key not authorized for this neuron

The key was made for a different neuron or agent. Use a key created on this neuron's START › Webhook.

Rate limit exceeded for this API key

The key went over its rate limit. This reply has status 429 and a Retry-After header with the number of seconds to wait before trying again; most HTTP clients and integration tools retry a 429 automatically. A wrong key or signature is a 401 instead. Send calls less often, or raise the limit on the API Keys page.

My address receives nothing

Check that SEND › API is on, that the Endpoint URL is reachable from the internet, and that the neuron's run finished without an error.