Agents API Webhooks

curl -X POST 'https://charlie-back.cloud-station.io/v1/projects/PROJECT_ID/conversations/telegram-123456789/messages' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'x-client-id: YOUR_CLIENT_ID' \
  -d '{
    "message": "Can you help me understand pricing?",
    "platform": "telegram",
    "response_webhook": "https://your-bot.example.com/cloudstation-webhook",
    "sender": {
      "id": "123456789",
      "name": "Jane Customer"
    },
    "external_message_id": "telegram:123456789:42"
  }'

{
  "status": "accepted",
  "adw_id": "abc12345",
  "conversation_id": "telegram-123456789",
  "conversation_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "message_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "task_id": "b3f1c9a2-4e5d-4f6a-8b7c-9d0e1f2a3b4c"
}

{
  "conversation_id": "telegram-123456789",
  "adw_id": "abc12345",
  "agent_id": "agent-uuid-or-wrapper-id",
  "message": {
    "content": "Yes — here is how pricing works...",
    "sender_type": "agent",
    "event_category": "response",
    "event_type": "assistant",
    "timestamp": 1783407290000
  },
  "delivery_id": "abc12345:7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "message_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "project_id": "prj_6efcfced-a176-4e4c-a989-9767c16fddf7",
  "platform": "telegram",
  "type": "message.assistant",
  "event_id": "01J8X9K3QYRZTS9V0N7M6P5C2A",
  "sequence": 42,
  "api_version": "2026-07-01"
}

X-CloudStation-Timestamp: 1778669193
X-CloudStation-Signature: v1=<hex-hmac-sha256>
X-CloudStation-Delivery-ID: abc12345:7c9e6679-7425-40de-944b-e07fc1f90ae7

v1=hex(HMAC_SHA256(webhook_secret, timestamp + "." + raw_request_body))

import { createHmac, timingSafeEqual } from 'node:crypto';
import express from 'express';

const app = express();
const WEBHOOK_SECRET = process.env.CLOUDSTATION_WEBHOOK_SECRET;
const SIGNATURE_TOLERANCE_MS = 5 * 60 * 1000;

type RawBodyRequest = express.Request & { rawBody?: Buffer };

app.use(
  express.json({
    verify: (req: RawBodyRequest, _res, buf) => {
      req.rawBody = Buffer.from(buf);
    },
  }),
);

function verifyCloudStationSignature(req: RawBodyRequest): boolean {
  if (!WEBHOOK_SECRET) return true;

  const timestamp = req.get('X-CloudStation-Timestamp');
  const signature = req.get('X-CloudStation-Signature');
  const rawBody = req.rawBody;

  if (!timestamp || !signature || !rawBody) return false;
  if (!signature.startsWith('v1=')) return false;

  const timestampSeconds = Number(timestamp);
  if (!Number.isFinite(timestampSeconds)) return false;

  const ageMs = Math.abs(Date.now() - timestampSeconds * 1000);
  if (ageMs > SIGNATURE_TOLERANCE_MS) return false;

  const expectedHex = createHmac('sha256', WEBHOOK_SECRET)
    .update(timestamp)
    .update('.')
    .update(rawBody)
    .digest('hex');

  const receivedHex = signature.slice(3);
  if (!/^[0-9a-fA-F]{64}$/.test(receivedHex)) return false;

  const expected = Buffer.from(expectedHex, 'hex');
  const received = Buffer.from(receivedHex, 'hex');

  return expected.length === received.length && timingSafeEqual(expected, received);
}

app.post('/cloudstation-webhook', async (req: RawBodyRequest, res) => {
  if (!verifyCloudStationSignature(req)) {
    return res.sendStatus(403);
  }

  // Acknowledge quickly. Do idempotency checks before sending to platforms.
  res.sendStatus(200);

  const payload = req.body;
  if (payload?.type === 'run.completed') return; // repeats the last message.assistant
  const content = payload?.message?.content;
  if (!content || typeof content !== 'string') return;

  // Send `content` back to Telegram, WhatsApp, Slack, your CRM, etc.
});

import hmac
import hashlib
import time
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
WEBHOOK_SECRET = 'your-webhook-secret'
SIGNATURE_TOLERANCE_SECONDS = 5 * 60

@app.post('/cloudstation-webhook')
async def cloudstation_webhook(request: Request):
    raw_body = await request.body()
    timestamp = request.headers.get('X-CloudStation-Timestamp')
    signature = request.headers.get('X-CloudStation-Signature')

    if WEBHOOK_SECRET:
        if not timestamp or not signature or not signature.startswith('v1='):
            raise HTTPException(status_code=401, detail='Missing signature')

        timestamp_seconds = int(timestamp)
        if abs(time.time() - timestamp_seconds) > SIGNATURE_TOLERANCE_SECONDS:
            raise HTTPException(status_code=403, detail='Stale signature')

        expected = hmac.new(
            WEBHOOK_SECRET.encode(),
            timestamp.encode() + b'.' + raw_body,
            hashlib.sha256,
        ).hexdigest()

        received = signature[3:]
        if not hmac.compare_digest(expected, received):
            raise HTTPException(status_code=403, detail='Invalid signature')

    payload = await request.json()
    content = payload.get('message', {}).get('content')
    if content and payload.get('type') != 'run.completed':
        # Send content back to your external platform.
        pass

    return {'ok': True}

const seen = new Map<string, number>();
const DEDUPE_TTL_MS = 5 * 60 * 1000;

function isDuplicate(id: string): boolean {
  const now = Date.now();
  for (const [key, expiresAt] of seen) {
    if (expiresAt <= now) seen.delete(key);
  }

  const existing = seen.get(id);
  if (existing && existing > now) return true;

  seen.set(id, now + DEDUPE_TTL_MS);
  return false;
}

class CloudStationAgentClient {
  constructor(
    private config: {
      apiUrl: string;
      projectId: string;
      apiKey: string;
      clientId: string;
      webhookBaseUrl: string;
      agentTemplateId?: string;
    },
  ) {}

  async sendMessage(input: {
    conversationId: string;
    message: string;
    platform: string;
    sender?: { id: string; name: string };
    externalMessageId?: string;
    contentBlocks?: unknown[];
  }) {
    const body: Record<string, unknown> = {
      message: input.message,
      platform: input.platform,
      response_webhook: `${this.config.webhookBaseUrl.replace(/\/+$/, '')}/cloudstation-webhook`,
    };

    if (this.config.agentTemplateId) body.agent_template_id = this.config.agentTemplateId;
    if (input.sender) body.sender = input.sender;
    if (input.externalMessageId) body.external_message_id = input.externalMessageId;
    if (input.contentBlocks?.length) body.content_blocks = input.contentBlocks;

    const response = await fetch(
      `${this.config.apiUrl.replace(/\/+$/, '')}/v1/projects/${this.config.projectId}/conversations/${input.conversationId}/messages`,
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': this.config.apiKey,
          'x-client-id': this.config.clientId,
        },
        body: JSON.stringify(body),
      },
    );

    if (!response.ok) {
      throw new Error(`Agents API error (${response.status}): ${await response.text()}`);
    }

    return response.json();
  }
}

WEBHOOK_BASE_URL=http://localhost:3000

WEBHOOK_BASE_URL=https://your-bot.example.com