Integrate with one call.

Before you start

Whoever designed the flow hands your team the credentials of the block that is yours. They are on the flow screen, in each block, under credentials. With each operation comes its Tracking ID.

Block ID

BLK-A1B2C3

Identifies the block in reports and in the trail. Public.

Block key

bk_live_9f8e7d6c5b4a3928

The block credential. Secret: it goes in the X-Block-Key header.

Callback URL

/api/live/callback

Where your system sends the POST.

Tracking ID

NT-2026-A3K7QX

One per operation, generated by the start block. Required in every callback.

The track, step by step

1. 01

   Receive the block credentials

   The ID, the key and the callback URL of your team’s block. One block, one key: it is not valid for another block or another flow.

2. 02

   Store the key as a secret

   In a vault or a server environment variable, never in the browser, the app or the repository. Whoever has the key lights up the block.

3. 03

   Carry the Tracking ID with the work

   The operation is opened in Nexo Trace and the start block generates the Tracking ID. It must reach your system with the work: in the order, the email, the ERP record. Without it the callback is rejected.

4. 04

   Send the callback when the step moves

   started when it begins (optional), progress for partial updates (optional), and completed or failed at the end. In a decision block, report the result in outcome.

5. 05

   Check the response and the board

   The response gives the new status of the block and the operation and which blocks were released. At the same moment, the block lights up on every company’s board.

Callback

One call per step event. The body is JSON; so is the response.

POSThttps://api.nexotrace.com.br/api/live/callback

Body

Status

• started

  The block starts running. data is stored as input.

• progress

  Partial update. The block keeps running; it can repeat.

• completed

  The block completes, data is stored as output, and the next blocks are released. On the end block, the operation closes.

• failed

  The block fails and the operation closes as failed.

Response

200 with the state after the callback. The Tracking ID also comes back in the X-Tracking-Id header, and every response carries X-Request-Id, the call number in the Nexo Trace log.

{
  "trackingId": "NT-2026-A3K7QX",
  "nodeKey": "analise",
  "blockRef": "BLK-A1B2C3",
  "stepStatus": "done",
  "operationStatus": "running",
  "activatedNodes": ["registro"],
  "eventSequence": 7
}

Decision blocks

In a decision block, completed requires an outcome equal to the label of one of the exits. The flow follows it; the others are marked as not taken. Without outcome, or with one that does not exist, the response is 400 with the list of options.

{
  "trackingId": "NT-2026-A3K7QX",
  "status": "completed",
  "outcome": "Approved"
}

Block key or participant key

Notice when the step is released

With the outbound webhook on, Nexo Trace notifies your system the moment a step of your participant is released: a POST with the Tracking ID, the step and what arrives for it (the fields of the block’s input contract). Whoever designed the flow sets the URL and sees the secret in Participants → Integrations.

The notice

{
  "id": "0b8f3c52-2d7e-4f7a-9d3a-6c1f5e2a9b10",
  "event": "step.activated",
  "occurredAt": "2026-09-28T14:05:12.000Z",
  "trackingId": "NT-2026-A3K7QX",
  "operation": {
    "flowName": "Crédito consignado",
    "description": "Proposta 4821",
    "startedAt": "2026-09-28T14:01:40.000Z"
  },
  "step": {
    "nodeKey": "analise",
    "blockRef": "BLK-A1B2C3",
    "label": "Análise de crédito",
    "kind": "task",
    "activatedAt": "2026-09-28T14:05:12.000Z",
    "dueAt": "2026-09-28T16:05:12.000Z"
  },
  "input": { "cliente": "Ana Lima" },
  "callback": { "url": "https://api.nexotrace.com.br/api/live/callback", "nodeKey": "analise" }
}

Checking the signature

Compute the HMAC-SHA256 of t, a dot and the body exactly as it arrived, with the secret, and compare it with v1 in constant time. Reject a notice whose t is more than 5 minutes old.

import crypto from 'node:crypto'

// corpo: o texto do corpo exatamente como chegou; assinatura: o header X-NexoTrace-Signature.
function avisoValido(corpo, assinatura, segredo) {
  const partes = Object.fromEntries(assinatura.split(',').map((p) => p.split('=')))
  const esperado = crypto.createHmac('sha256', segredo).update(`${partes.t}.${corpo}`).digest('hex')
  const recente = Math.abs(Date.now() / 1000 - Number(partes.t)) < 300
  return recente && esperado.length === partes.v1?.length &&
    crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(partes.v1))
}

• Respond 2xx within 10 seconds. Any other status, or no response, counts as a failure: Nexo Trace retries in 1, 5, 25 and 125 minutes and stops after the fifth attempt.
• The notice does not follow redirects and goes only to a public address with https.
• Notices come from the IP 157.254.207.182. If your system only accepts known addresses, allow this one.
• Did the step move before the notice went out (through another channel)? The notice is not sent.
• The notice does not carry the block key: your system already has it. The step’s answer is still the usual callback.

Inbound webhook, in your system’s format

If your system already fires webhooks in its own format, there is no need to adapt it to the callback: whoever designed the flow creates an inbound webhook (Participants → Integrations) with a mapping that says where each thing is in your JSON. The URL carries a token and is shown once; Nexo Trace keeps only the hash.

Mapping and notice

{
  "trackingId": "$.pedido.ref",
  "nodeKey": "analise",
  "status": "$.situacao",
  "statusMap": { "APROVADO": "completed", "EM_ANALISE": "progress", "RECUSADO": "failed" },
  "data": "$.pedido"
}

POST https://api.nexotrace.com.br/api/hooks/wh_…
Content-Type: application/json

{ "situacao": "APROVADO", "pedido": { "ref": "NT-2026-A3K7QX", "contrato": "CCB-004812" } }

The response is the same as the callback’s. A notice that does not match the mapping gets 400 saying which field was not found. The URL only reaches its participant’s blocks, in the owner account’s operations: 403 and 404 as with the participant key; deleted or deactivated URL, 401.

No-code tools

n8n, Make, Zapier and Power Automate talk to Nexo Trace through each one’s HTTP module: to notify, a POST to the callback or to the inbound webhook; to receive, the URL of one of the tool’s triggers in the step released notice.

Keep the block key, the inbound webhook URL and the secret in the tool’s credentials or variables, never in the flow text.

Batch spreadsheet

Many steps at once: a CSV or XLSX with one row per step, sent with the participant key. GET /api/live/batch/template returns the template with its steps that are waiting.

curl -X POST https://api.nexotrace.com.br/api/live/batch \
  -H "X-Player-Key: $NEXOTRACE_PLAYER_KEY" \
  -F "file=@etapas.xlsx"

{
  "fileName": "etapas.xlsx",
  "duplicate": false,
  "total": 2,
  "ok": 1,
  "errors": 1,
  "rows": [
    { "line": 2, "trackingId": "NT-2026-A3K7QX", "block": "analise", "status": "ok", "stepStatus": "done", "operationStatus": "running" },
    { "line": 3, "trackingId": "NT-2026-B7M2PQ", "block": "analise", "status": "error", "error": "A etapa Análise de crédito não está aguardando resposta." }
  ]
}

• Each row is applied on its own: an error in one does not undo the others. The response brings the result row by row, with the Tracking ID.
• The step must be waiting; the participant key rules apply to each row (only its blocks, only the owner account’s operations).
• The same file is not applied twice: sending it again returns the first result, with duplicate: true.
• Up to 5 MB and 1,000 rows. CSV in UTF-8 (or Excel’s default), separated by comma, semicolon or tab; XLSX, the first sheet.

MCP server for AI

AI assistants that speak MCP (Model Context Protocol), such as Claude Code, Cursor and VS Code, use Nexo Trace through this server’s tools, under the same rules as the API. The transport is HTTP, and the credential goes in Authorization: Bearer. What the AI reaches depends on the credential:

https://mcp.nexotrace.com.br/mcp

Connect

In Claude Code, one command; in other clients, the server configuration in JSON. Replace the credential with yours and keep it as a secret.

claude mcp add --transport http nexotrace https://mcp.nexotrace.com.br/mcp \
  --header "Authorization: Bearer $NEXOTRACE_TOKEN"

{
  "mcpServers": {
    "nexotrace": {
      "type": "http",
      "url": "https://mcp.nexotrace.com.br/mcp",
      "headers": { "Authorization": "Bearer pk_…" }
    }
  }
}

• report_step follows the callback rule and only moves a step that is waiting. The trail records source: mcp.
• The participant’s AI only sees what is its own and what reaches it: the step’s input fields, never another participant’s output or the operation’s trail.
• The personal token does not report steps (moving a step is up to the participant) and does not open the rest of the API.
• Creating and changing flows and participants (create_flow, update_flow, create_participant, update_participant) show up in the server's list, but only the assistant inside Nexo Trace uses them, on behalf of whoever is on the screen. A personal token and the keys do not change the design or the registry.
• An operation or flow the credential does not reach answers as not found.
• Tool descriptions are in English, like the API field names; messages follow Accept-Language.

Errors

Every error responds { "error": "…", "trackingId": "…" }, with a sentence that says what happened and what to do. The sentence follows the Accept-Language header (pt-BR, en or es).

Examples

The same callback in four languages. Replace the key and the Tracking ID with yours.

curl -X POST https://api.nexotrace.com.br/api/live/callback \
  -H "Content-Type: application/json" \
  -H "X-Block-Key: $NEXOTRACE_BLOCK_KEY" \
  -d '{"trackingId":"NT-2026-A3K7QX","status":"completed","data":{"contract":"CCB-004812"}}'

Good practices

• Retry the call only when there was no response (network error or 5xx). A repeated callback records another event in the trail.
• Keep the X-Request-Id of the responses: with it, any call can be found in the log to investigate a problem.
• Send in data what the operation needs to prove, and only that: the content stays in the audit trail and in the reports, which the operation’s companies download.
• Wait for the response before the next event of the same block: the trail order is the order in which callbacks arrive.

Test before connecting your system

On an operation’s board, anyone with edit access to the flow can use "Simulate participants": the button fires real callbacks, with each block’s key, and shows the block lighting up. A new account starts on Free, with no limits in the first 30 days.