TensoraAI API & Integration Reference

Common integration approaches

These are the five shapes almost every integration takes. Which one fits is decided by what the connected system supports, not by what would be convenient — so not every approach is available on every project.

What Step 4 validates before go-live

An integration is not finished when the happy path works. It is finished when the failure paths are understood and a person can pick up whatever the workflow could not complete.

• Authentication
• Request payload
• Input validation
• Responses
• Error handling
• Retries
• Rate limits
• Logging
• Human fallback

Server variables vs. public variables

Modern frameworks split configuration in two. Server-side variables are read only by code running on the server and never leave it. Public variables are inlined into the JavaScript sent to every visitor — in Next.js those are the ones prefixed NEXT_PUBLIC_, and they are appropriate for things that are already public, such as a site URL or a publishable widget id.

Code examples

The same request in three languages. Note that in each one the token is read from an environment variable rather than written into the source — that is the point of the example as much as the HTTP call is.

curl -X POST https://api.example.com/v1/leads \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Customer",
    "email": "customer@example.com"
  }'

const response = await fetch("https://api.example.com/v1/leads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Example Customer",
    email: "customer@example.com",
  }),
});

const data = await response.json();

import os
import requests

response = requests.post(
    "https://api.example.com/v1/leads",
    headers={
        "Authorization": f"Bearer {os.environ['API_TOKEN']}"
    },
    json={
        "name": "Example Customer",
        "email": "customer@example.com"
    },
)

data = response.json()

{
  "event": "lead.created",
  "timestamp": "2026-08-21T12:00:00Z",
  "data": {
    "name": "Example Customer",
    "email": "customer@example.com",
    "source": "website"
  }
}

A predictable envelope — an event name, a timestamp, and a data object — is what lets one receiving workflow handle many event types without a separate parser for each. The exact shape on a real project is set by whichever system is doing the sending.

Example business events

These event names demonstrate common implementation patterns and are not guaranteed public TensoraAI event identifiers.

Securing webhooks

A webhook URL is a door into your workflow that anyone can knock on. These are the practices that decide whether knocking is enough to get in.

• Accept events over HTTPS only.
• Verify a signature or shared secret on every request.
• Reject payloads that fail verification, without explaining why.
• Validate the payload against a schema before reading any field.
• Check the event timestamp where the sender provides one.
• Prevent replay by rejecting stale or already-processed event ids.
• Rate limit the endpoint so a broken sender cannot flood it.
• Log failed validations — they are the first sign of an attack or a misconfigured sender.
• Never trust a client-supplied identifier as proof of who the caller is.
• Respond quickly; senders time out and retry.
• Move slow work to an asynchronous job rather than holding the connection open.

Common chatbot actions

What any given chatbot can do is set by the integrations configured behind it, not by the widget itself.

• Answer frequently asked questions
• Explain products and services
• Qualify leads before a human sees them
• Collect customer information
• Create a CRM record
• Retrieve approved business data
• Create a support request
• Trigger an automation
• Hand the conversation to a person

Example: lead qualification workflow

A concrete version of the shape above. Note that an unqualified lead is not discarded — it takes a different path.

Technologies these workflows are built from

A given project uses some of these, never all of them. The right answer depends on where your data already lives, what your team can maintain, and what the connected vendors support.

• n8n
• Zapier
• Make
• Next.js route handlers
• Webhooks
• Supabase / Postgres
• Serverless functions
• Transactional email services
• CRM APIs

Six failures worth telling apart

Treating all six the same way is the most common integration bug we are asked to fix: a workflow that retries a validation error forever, or gives up on a vendor that was down for ninety seconds.

Retry behaviour

Designing for 429 Too Many Requests

A 429 is not an error in the usual sense — it is the other system asking the workflow to slow down. Treating it as a failure is what turns a busy afternoon into a broken integration.

How TensoraAI uses these patterns

Four of these workflows are running on this website right now. They are described at the level of what they do, not how they are wired — but every one of them is something you can trigger yourself and watch happen.

API vs. webhook

The one distinction worth understanding before an integration conversation. Everything else on this page is a variation on these two directions.