Home
Developers

API and events spec

On this page Spec: the request and event formats are published and stable for you to build on, and they're enabled for your business on request on Professional and above. The only live endpoint today is the health check /health , and the status of every endpoint is written in the guide.

Open the full API reference

Authentication

A key in the header

Every request carries your key in the Authorization. We issue your key on activation and revoke it whenever you ask, and it isn't shown again after handover.

We recommend a separate key for each integration, so revoking one doesn't stop the rest.

And the base URL is your own domain, because every customer has their own instance of Naateq.

# fetch a customer record — replace the domain with your own server
curl https://bot.example.sa/api/v1/customers/966501234567 \
  -H "Authorization: Bearer $NAATEQ_KEY" \
  -H "Accept: application/json"

Webhooks

Events you receive once they're enabled

You register a single URL, and every event arrives there as JSON with a signature X-Naateq-Signature.

These events are a Spec: their format is fixed and published so you can build on it, and they are switched on for your business on request. Status of each event in the reference.

message.receivedA message arrived from a customer. Carries the text, the sender number, and the classified intent.

reply.sentThe system replied. Carries the reply, its source (automated / tool / human), and the processing time.

stage.changedThe lead moved between the four stages. Carries the previous stage and the new one.

quote.issuedA quote was issued. Carries the document number, the total, and the PDF link.

contract.approvedThe owner approved sending a contract. Carries the contract number and its value.

handoff.requestedA handover to a human was requested. Carries the escalation reason and the full conversation text.

guard.blockedThe input filter blocked a message. Carries the attempt type and the blocked text.

POST /your-endpoint
X-Naateq-Signature: t=1780000000,v1=5f2b…

{
  "event": "quote.issued",
  "created_at": "2026-08-04T09:31:02.771Z",
  "data": {
    "doc_number": "NQ-Q-260804-058", "customer": { "number": "966501234567", "name": "Mohammed Al-Harbi" }, "total": 420000,
    "currency": "SAR",
    "pdf_url": "https://bot.example.sa/api/v1/documents/NQ-Q-260804-058/pdf"
  }
}

Verifying the signature

Never trust an unsigned request

Compute HMAC-SHA256 over t + "." + body with the webhook secret, and compare it against the value in v1. Reject any request older than five minutes.

import crypto from "node:crypto";

export function verify(raw, header, secret) {
  const [t, v1] = header.split(",").map(p => p.split("=")[1]);
  if (Math.abs(Date.now()/1000 - +t) > 300) return false;
  const expect = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${raw}`)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expect), Buffer.from(v1)
  );
}

Use cases

What you can build on this API once it's enabled

Your data in your system

Pull chats, customers and quotes into your internal system and display them however you like.

GET /api/v1/conversations

Sync with your CRM

With every new customer you receive a webhook with their stage and source, so they enter your sales pipeline in seconds with no manual entry.

stage.changed

Alert your team where it works

Escalate the chat to Slack, Telegram or your ticketing system the moment a customer asks for a staff member or asks for a discount above the cap you set.

handoff.requested

Limits and data policy

Request limits, retries and timeouts below Spec, and they apply once the API is enabled for your business.

Usage limits and the data retention policy
Item	Value
Request limit	120 / minute per key
Over the limit	`429` with the header `Retry-After`
Webhook retries	5 attempts with exponential backoff over 24 hours
Your endpoint response timeout	5 seconds
Where data is stored	On your server if you run it yourself, or on our servers on managed operation. On managed operation, chat text is processed at a cloud AI provider we name in your contract
Retention and deletion	You set both, and the system doesn't delete anything automatically

Need an endpoint that does not exist yet?

We build endpoints on request, so tell us what you're building.

Start your free trial Message the technical team