Workflow webhooks

Use a workflow webhook for a specific configured lifecycle trigger, such as registration, KYC completion, a deposit candidate, account status, or a reward redemption. The webhook delivers an event to a workflow. It does not by itself prove that a user field, balance, or widget has changed.

Flow

1. Receive a committed broker event. Keep its stable source identity and event time. A retry timestamp is not a business event timestamp.
2. Call the provisioned handshake URL. Send the workflow API key in the header required by that trigger. The documented route shape ends in /handshake; use the complete URL supplied for the environment rather than guessing a host or trigger ID.
3. Read data.sessionToken. The current service source uses a 300-second session-token TTL. Prefer the returnedexpiresIn when present and exchange again before expiry.
4. Call the main webhook. Send the session token inx-session-token and send the payload required by that workflow.

async function sendRegistration(user) {
  const handshakeUrl = process.env.RAI_WORKFLOW_HANDSHAKE_URL;
  const webhookUrl = process.env.RAI_WORKFLOW_WEBHOOK_URL;
  const workflowApiKey = process.env.RAI_WORKFLOW_API_KEY;

  if (!handshakeUrl || !webhookUrl || !workflowApiKey) {
    throw new Error('Missing provisioned workflow settings');
  }

  const handshake = await fetch(handshakeUrl, {
    method: 'POST',
    headers: {
      Authorization: workflowApiKey,
      'Content-Type': 'application/json',
    },
  });

  if (!handshake.ok) {
    throw new Error(`Handshake failed: ${handshake.status}`);
  }

  const handshakeBody = await handshake.json();
  const sessionToken = handshakeBody.data?.sessionToken;
  if (!sessionToken) {
    throw new Error('Handshake did not return data.sessionToken');
  }

  const event = {
    eventType: 'user.registered',
    eventId: user.registrationEventId,
    customerId: user.customerId,
    occurredAt: user.registeredAt,
  };

  const response = await fetch(webhookUrl, {
    method: 'POST',
    headers: {
      'x-session-token': sessionToken,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(event),
  });

  if (!response.ok) {
    throw new Error(`Webhook request failed: ${response.status}`);
  }

  // Record the HTTP status. Check workflow history and saved state separately.
}

The environment values in this example are named placeholders. The Returning.AI setup owner must provide the exact handshake URL, main webhook URL, trigger reference, required permission, and selected auth mode for the environment.

Response shape

The handshake response places the session token underdata.sessionToken. A current source-backed TTL is 300 seconds, but the returned expiry and the provisioned trigger configuration are the values to use at runtime.

{
  "data": {
    "sessionToken": "<SHORT_LIVED_SESSION_TOKEN>",
    "expiresIn": 300
  }
}

Payload guidance

Webhook payloads belong to the configured workflow. Lifecycle examples commonly use camelCase names, while Event Ingest trading rows commonly use snake_case. Do not copy one contract into the other without checking the trigger configuration.

{
  "eventType": "user.registered",
  "eventId": "registration-CUSTOMER_1001-2026-09-07",
  "customerId": "CUSTOMER_1001",
  "occurredAt": "2026-09-07T09:00:00.000Z",
  "tradingAccounts": [
    {
      "platform": "mt5",
      "server": "broker-live-1",
      "accountLogin": "ACCOUNT_2001"
    }
  ]
}

• Use a stable broker customer identifier that matches the enrollment and widget identity. Trading account keys remain separate from the canonical customer.
• Keep eventId stable across an exact retry. It is a business identity in this example, not a generic promise that the webhook controller deduplicates it.
• Preserve the source event's occurredAt. Do not callnew Date() again while retrying an old event.
• Send only the fields required by the configured workflow. Never send access keys, trading passwords, session tokens, or other private credentials in the event body.

Keep event types separate

Separate events when their eligibility, timing, or reward rule differs. Names below are examples for workflow configuration, not a universal endpoint schema.

Retries and business dedupe

The generic webhook controller creates an execution identity from the trigger, current request time, and a random value. A caller-suppliedeventId therefore does not create universal dedupe by itself. The workflow or downstream mutation needs an approved stable business key, or the trigger owner must provide another supported contract.

• Once reconciliation and the configured replay policy permit a retry, keep the same eventId, customer identity, source account, and original occurredAt when the payload is unchanged.
• If the result is unknown, reconcile the request and workflow state before sending again. A timeout is not proof that the first execution failed.
• If a payload is corrected, use the configured correction or compensation path. A new event ID can cause a second additive side effect.
• If referral follow-up fails after enrollment, repair that relationship separately. Do not retry user creation just because a later referral step failed.

Bulk update results callback

When a workflow runs a Users Bulk Update step, the step only queues a bulk update job, and the job can finish after the workflow has ended. Instead of polling Get bulk update job status, the step can send the job's final result to an HTTPS endpoint you run.

Set it on the step in the dashboard: Settings > Integration > Data Workflows, open the workflow, select the Users Bulk Update step and switch on Callback URL. A community owner or admin can change it. Files uploaded with Bulk update users from CSV or the premium currency upload never send one; poll those jobs instead.

Each job keeps the settings the step had when it was queued. Changing the step later, or switching the callback off, doesn't change jobs already in the queue.

The request

Once per job, after it ends completed or failed, Returning.AI sends a POST with a JSON body, usually within a minute of the job finishing. Nothing is sent while the job is queued or running. The request carries these headers and no credentials or signature, so use a hard-to-guess path on your endpoint and treat the body as a notice: confirm the job with Get bulk update job status and your API key before you act on it.

POST /your/bulk-results/path HTTP/1.1
Content-Type: application/json
Accept: application/json
User-Agent: returning-ai-bulk-update-webhook/1.0
Idempotency-Key: bulk-update:66f000000000000000000701:completed

A job that finished, with one failed row:

{
  "event": "users.bulk-update.completed",
  "jobId": "66f000000000000000000701",
  "communityId": "66f000000000000000000001",
  "status": "completed",
  "name": "Nightly coins top-up",
  "workflowId": "66f000000000000000000002",
  "workflowNodeId": "66f000000000000000000003",
  "completedAt": "2026-09-30T02:00:05.000Z",
  "csvUrl": "<resultsCsvUrl>",
  "summary": {
    "total": 2,
    "processed": 2,
    "successful": 1,
    "failed": 1,
    "skipped": 0
  },
  "errors": {
    "message": "1 user failed"
  }
}

A job that failed because the file was rejected:

{
  "event": "users.bulk-update.failed",
  "jobId": "66f000000000000000000702",
  "communityId": "66f000000000000000000001",
  "status": "failed",
  "name": "Nightly coins top-up",
  "workflowId": "66f000000000000000000002",
  "workflowNodeId": "66f000000000000000000003",
  "errors": {
    "message": "Invalid headers: Coins"
  }
}

A field that doesn't apply is left out, not sent empty. For each failed row's error code, read Get bulk update job details with the jobId. The results file holds your traders' emails, so treat the csvUrl link as confidential and keep it out of logs and shared channels. Download the file when the callback arrives.

Responding, retries and duplicates

• Return any 2xx status within 15 seconds, then do the work. Keep the response body under 64 KB.
• A timeout, a network error, a status outside 2xx, a redirect or a larger body counts as a failed delivery. Redirects are not followed.
• A failed delivery is retried with the same body and headers, about 1, 2, 4 and 8 minutes apart, for at most 5 attempts. After that the callback stops for good; check the job with Get bulk update job status instead. Delivery problems never change the job or run it again.
• The same callback can arrive more than once. Store each Idempotency-Key (bulk-update:<jobId>:<status>) and ignore repeats.

Specific API operation versus workflow

Choose by the configured operation, not by a claim that one family always finishes synchronously. An API response confirms that operation's response only; a workflow response confirms queue acceptance. Ask the platform owner for the exact host, path, credential permission, accepted identifier, and readback operation before sending an API request.

Direct-key mode

Some configured triggers can accept a workflow API key directly on the main webhook when token exchange is disabled. This is a configuration choice, not a blanket legacy rule. Before using it, have the Returning.AI owner confirm that the trigger has token exchange disabled, the exact header and URL, the key permission, and the retry/readback behavior. Never put that key in browser code.

Next step

After a registration event is accepted, finish enrollment and identity readback before opening the widget quickstart. For trading facts, continue to the trading volume and rewards guide. For buffered delivery, use the SQS data feed guide.