Crear integraciones personalizadas de chatbots con webhooks y APIs

┌──────────────┐     Ocurre evento    ┌──────────────────┐
│   Plataforma │ ──── HTTP POST ────▶ │  Tu endpoint     │
│   chatbot    │                      │   webhook        │
└──────────────┘                      └────────┬─────────┘
                                               │
                                      Procesar evento
                                               │
                                      ┌────────▼─────────┐
                                      │ Sistema externo  │
                                      │ (CRM, helpdesk,  │
                                      │ sistema pedidos) │
                                      └──────────────────┘

typescript
// Lo que la plataforma de chatbot envía a tu webhook
{
  "event": "conversation.escalated",
  "timestamp": "2026-03-30T14:22:00Z",
  "data": {
    "conversationId": "conv_abc123",
    "customerId": "cust_456",
    "customerEmail": "user@example.com",
    "messages": [
      { "role": "user", "content": "My order hasn't arrived and it's been 2 weeks" },
      { "role": "assistant", "content": "I apologize for the delay. Let me look into this..." },
      { "role": "user", "content": "I want to speak to someone" }
    ],
    "metadata": {
      "agentConfidence": 0.32,
      "escalationReason": "customer_requested",
      "detectedIntent": "shipping_complaint"
    }
  }
}

typescript
// Bien: confirmar de inmediato, procesar async
app.post("/webhooks/chatbot", async (req, res) => {
  // Validar firma primero (ver siguiente sección)
  if (!verifySignature(req)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  // Confirmar recepción
  res.status(200).json({ received: true });

  // Procesar de forma asíncrona
  processWebhookEvent(req.body).catch((err) => {
    console.error("Webhook processing failed:", err);
  });
});

typescript
import crypto from "crypto";
import type { Request } from "express";

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET!;

function verifySignature(req: Request): boolean {
  const signature = req.headers["x-webhook-signature"] as string;
  if (!signature) return false;

  const expectedSignature = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest("hex");

  // Comparación timing-safe para prevenir ataques de timing
  return crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expectedSignature, "hex")
  );
}

typescript
import { Redis } from "ioredis";

const redis = new Redis(process.env.REDIS_URL);

async function processWebhookEvent(event: WebhookEvent): Promise<void> {
  const eventId = event.data.conversationId + ":" + event.timestamp;

  // Revisar si ya procesamos este evento
  const alreadyProcessed = await redis.get(`webhook:processed:${eventId}`);
  if (alreadyProcessed) {
    console.log(`Skipping duplicate event: ${eventId}`);
    return;
  }

  // Procesar el evento
  await handleEvent(event);

  // Marcar como procesado con TTL de 24 h
  await redis.set(`webhook:processed:${eventId}`, "1", "EX", 86400);
}

typescript
interface CRMContact {
  email: string;
  properties: Record<string, string>;
}

async function syncConversationToCRM(event: ConversationEndedEvent): Promise<void> {
  const { customerEmail, messages, metadata } = event.data;

  // Crear o actualizar el contacto en tu CRM
  const contact = await crmClient.contacts.createOrUpdate({
    email: customerEmail,
    properties: {
      last_chatbot_interaction: new Date().toISOString(),
      chatbot_resolution_status: metadata.resolved ? "resolved" : "unresolved",
      chatbot_detected_intent: metadata.detectedIntent,
    },
  });

  // Registrar la conversación como actividad/nota
  await crmClient.activities.create({
    contactId: contact.id,
    type: "chatbot_conversation",
    body: summarizeConversation(messages),
    metadata: {
      conversationId: event.data.conversationId,
      messageCount: messages.length,
      duration: metadata.durationSeconds,
    },
  });
}

typescript
async function createSupportTicket(event: EscalationEvent): Promise<string> {
  const { customerId, customerEmail, messages, metadata } = event.data;

  const ticket = await helpdeskClient.tickets.create({
    subject: `Chatbot escalation: ${metadata.detectedIntent}`,
    requester: { email: customerEmail },
    priority: determinePriority(metadata),
    tags: ["chatbot-escalation", metadata.detectedIntent],
    description: formatTicketDescription(messages, metadata),
    customFields: {
      chatbot_conversation_id: event.data.conversationId,
      escalation_reason: metadata.escalationReason,
      ai_confidence_score: metadata.agentConfidence,
    },
  });

  return ticket.id;
}

function determinePriority(metadata: EscalationMetadata): "low" | "normal" | "high" | "urgent" {
  if (metadata.escalationReason === "customer_frustrated") return "high";
  if (metadata.agentConfidence < 0.2) return "high";
  if (metadata.detectedIntent.includes("billing")) return "normal";
  return "normal";
}

function formatTicketDescription(
  messages: Message[],
  metadata: EscalationMetadata
): string {
  const transcript = messages
    .map((m) => `**${m.role === "user" ? "Customer" : "AI"}:** ${m.content}`)
    .join("\n\n");

  return `## Chatbot Escalation

**Reason:** ${metadata.escalationReason}
**AI Confidence:** ${(metadata.agentConfidence * 100).toFixed(0)}%
**Detected Intent:** ${metadata.detectedIntent}

## Conversation Transcript

${transcript}`;
}

typescript
// Esta es una llamada API saliente desde el chatbot, no un webhook
// Registrada como una "herramienta" que el chatbot puede invocar

async function lookupOrder(orderId: string, customerEmail: string): Promise<OrderInfo> {
  const response = await fetch(`${ORDER_API_URL}/orders/${orderId}`, {
    headers: {
      Authorization: `Bearer ${ORDER_API_TOKEN}`,
      "Content-Type": "application/json",
    },
  });

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

  const order = await response.json();

  // Verificar que el pedido pertenece a este cliente
  if (order.customerEmail !== customerEmail) {
    throw new Error("Order does not belong to this customer");
  }

  return {
    orderId: order.id,
    status: order.status,
    trackingNumber: order.trackingNumber,
    estimatedDelivery: order.estimatedDelivery,
    items: order.items.map((i: OrderItem) => ({
      name: i.productName,
      quantity: i.quantity,
    })),
  };
}

typescript
// Webhook desde tu CMS cuando se publica o actualiza un artículo de ayuda
app.post("/webhooks/cms-update", async (req, res) => {
  if (!verifySignature(req)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  res.status(200).json({ received: true });

  const { articleId, action, content, title, url } = req.body;

  switch (action) {
    case "published":
    case "updated":
      await chatbotKB.upsertDocument({
        externalId: articleId,
        title,
        content,
        sourceUrl: url,
        lastUpdated: new Date().toISOString(),
      });
      break;
    case "unpublished":
      await chatbotKB.deleteDocument({ externalId: articleId });
      break;
  }
});

bash
mkdir chatbot-webhook && cd chatbot-webhook
npm init -y
npm install express dotenv
npm install -D typescript @types/express @types/node tsx
npx tsc --init

typescript
// src/server.ts
import express from "express";
import crypto from "crypto";
import dotenv from "dotenv";

dotenv.config();

const app = express();
app.use(express.json());

// --- Configuración ---
const PORT = process.env.PORT || 3000;
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET!;
const HELPDESK_API_URL = process.env.HELPDESK_API_URL!;
const HELPDESK_API_KEY = process.env.HELPDESK_API_KEY!;

// --- Tipos ---
interface WebhookPayload {
  event: string;
  timestamp: string;
  data: {
    conversationId: string;
    customerId: string;
    customerEmail: string;
    customerName?: string;
    messages: Array<{ role: "user" | "assistant"; content: string }>;
    metadata: {
      agentConfidence: number;
      escalationReason: string;
      detectedIntent: string;
      sessionDurationSeconds: number;
    };
  };
}

interface TicketResponse {
  id: string;
  url: string;
  status: string;
}

// --- Verificación de firma ---
function verifyWebhookSignature(
  payload: string,
  signature: string | undefined
): boolean {
  if (!signature) return false;

  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(payload)
    .digest("hex");

  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature, "hex"),
      Buffer.from(expected, "hex")
    );
  } catch {
    return false;
  }
}

// --- Cliente API de helpdesk ---
async function createTicket(payload: WebhookPayload): Promise<TicketResponse> {
  const { data } = payload;

  const ticketBody = {
    subject: `[Chatbot Escalation] ${data.metadata.detectedIntent}`,
    requester: {
      email: data.customerEmail,
      name: data.customerName || "Customer",
    },
    priority: data.metadata.agentConfidence < 0.3 ? "high" : "normal",
    tags: ["chatbot-escalation", data.metadata.detectedIntent],
    description: buildTicketDescription(data),
    custom_fields: {
      conversation_id: data.conversationId,
      escalation_reason: data.metadata.escalationReason,
      ai_confidence: data.metadata.agentConfidence,
      session_duration: data.metadata.sessionDurationSeconds,
    },
  };

  const response = await fetch(`${HELPDESK_API_URL}/tickets`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${HELPDESK_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(ticketBody),
  });

  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(
      `Helpdesk API error: ${response.status} - ${errorBody}`
    );
  }

  return response.json() as Promise<TicketResponse>;
}

function buildTicketDescription(
  data: WebhookPayload["data"]
): string {
  const transcript = data.messages
    .map((m) => {
      const speaker = m.role === "user" ? "Customer" : "AI Agent";
      return `**${speaker}:** ${m.content}`;
    })
    .join("\n\n");

  return `## Escalation Details

| Field | Value |
|-------|-------|
| Conversation ID | ${data.conversationId} |
| Escalation Reason | ${data.metadata.escalationReason} |
| AI Confidence | ${(data.metadata.agentConfidence * 100).toFixed(0)}% |
| Detected Intent | ${data.metadata.detectedIntent} |
| Session Duration | ${data.metadata.sessionDurationSeconds}s |

## Conversation Transcript

${transcript}`;
}

// --- Endpoint webhook ---
app.post("/webhooks/escalation", (req, res) => {
  // Paso 1: verificar firma
  const rawBody = JSON.stringify(req.body);
  const signature = req.headers["x-webhook-signature"] as string;

  if (!verifyWebhookSignature(rawBody, signature)) {
    console.warn("Invalid webhook signature received");
    return res.status(401).json({ error: "Invalid signature" });
  }

  const payload = req.body as WebhookPayload;

  // Paso 2: validar tipo de evento
  if (payload.event !== "conversation.escalated") {
    return res.status(200).json({ skipped: true, reason: "Unhandled event type" });
  }

  // Paso 3: confirmar de inmediato
  res.status(200).json({ received: true, conversationId: payload.data.conversationId });

  // Paso 4: procesar de forma asíncrona
  createTicket(payload)
    .then((ticket) => {
      console.log(
        `Ticket created: ${ticket.id} for conversation ${payload.data.conversationId}`
      );
    })
    .catch((err) => {
      console.error(
        `Failed to create ticket for ${payload.data.conversationId}:`,
        err
      );
      // En producción: enviar a una dead-letter queue para retry
    });
});

// Health check
app.get("/health", (_, res) => {
  res.status(200).json({ status: "ok" });
});

app.listen(PORT, () => {
  console.log(`Webhook server listening on port ${PORT}`);
});

bash
# .env
PORT=3000
WEBHOOK_SECRET=your-shared-secret-from-chatbot-platform
HELPDESK_API_URL=https://api.yourhelpdesk.com/v2
HELPDESK_API_KEY=your-helpdesk-api-key

bash
npx tsx src/server.ts

typescript
const response = await fetch(apiUrl, {
  headers: {
    "X-API-Key": process.env.EXTERNAL_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

typescript
class OAuth2Client {
  private accessToken: string | null = null;
  private tokenExpiry: number = 0;

  constructor(
    private clientId: string,
    private clientSecret: string,
    private tokenUrl: string
  ) {}

  async getAccessToken(): Promise<string> {
    // Devolver token cacheado si sigue siendo válido
    if (this.accessToken && Date.now() < this.tokenExpiry - 60_000) {
      return this.accessToken;
    }

    const response = await fetch(this.tokenUrl, {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({
        grant_type: "client_credentials",
        client_id: this.clientId,
        client_secret: this.clientSecret,
        scope: "tickets:write contacts:read",
      }),
    });

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

    const data = await response.json();
    this.accessToken = data.access_token;
    this.tokenExpiry = Date.now() + data.expires_in * 1000;

    return this.accessToken;
  }

  async authenticatedFetch(url: string, options: RequestInit = {}): Promise<Response> {
    const token = await this.getAccessToken();
    return fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        Authorization: `Bearer ${token}`,
      },
    });
  }
}

typescript
import jwt from "jsonwebtoken";

function generateServiceToken(): string {
  return jwt.sign(
    {
      iss: "chatbot-webhook-service",
      sub: "webhook-integration",
      aud: "helpdesk-api",
      iat: Math.floor(Date.now() / 1000),
      exp: Math.floor(Date.now() / 1000) + 300, // Expira en 5 minutos
    },
    process.env.JWT_PRIVATE_KEY!,
    { algorithm: "RS256" }
  );
}

typescript
interface RetryConfig {
  maxRetries: number;
  baseDelayMs: number;
  maxDelayMs: number;
}

async function withRetry<T>(
  fn: () => Promise<T>,
  config: RetryConfig = { maxRetries: 3, baseDelayMs: 1000, maxDelayMs: 30000 }
): Promise<T> {
  let lastError: Error | null = null;

  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      lastError = err as Error;

      if (attempt === config.maxRetries) break;

      // No reintentar errores de cliente (4xx excepto 429)
      if (err instanceof ApiError && err.status >= 400 && err.status < 500 && err.status !== 429) {
        throw err;
      }

      // Exponential backoff con jitter
      const exponentialDelay = config.baseDelayMs * Math.pow(2, attempt);
      const jitter = Math.random() * config.baseDelayMs;
      const delay = Math.min(exponentialDelay + jitter, config.maxDelayMs);

      console.warn(
        `Attempt ${attempt + 1} failed, retrying in ${Math.round(delay)}ms:`,
        (err as Error).message
      );

      await sleep(delay);
    }
  }

  throw lastError;
}

function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

// Uso
const ticket = await withRetry(() => createTicket(payload), {
  maxRetries: 3,
  baseDelayMs: 1000,
  maxDelayMs: 30000,
});

typescript
async function processWebhookWithDLQ(payload: WebhookPayload): Promise<void> {
  try {
    await withRetry(() => createTicket(payload));
  } catch (err) {
    console.error("All retries exhausted. Pushing to DLQ:", err);

    await deadLetterQueue.push({
      payload,
      error: (err as Error).message,
      failedAt: new Date().toISOString(),
      retryCount: 3,
    });

    // Alertar al equipo
    await alerting.notify({
      channel: "webhook-failures",
      message: `Webhook processing failed for conversation ${payload.data.conversationId}`,
      severity: "warning",
    });
  }
}

bash
# Terminal 1: ejecutar tu servidor
npx tsx src/server.ts

# Terminal 2: exponer puerto 3000
ngrok http 3000

bash
# Generar una firma válida
SECRET="your-shared-secret"
PAYLOAD='{"event":"conversation.escalated","timestamp":"2026-03-30T14:22:00Z","data":{"conversationId":"conv_test123","customerId":"cust_456","customerEmail":"test@example.com","messages":[{"role":"user","content":"I need help"},{"role":"assistant","content":"Let me connect you with a human agent."}],"metadata":{"agentConfidence":0.25,"escalationReason":"low_confidence","detectedIntent":"general_inquiry","sessionDurationSeconds":45}}}'

SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST http://localhost:3000/webhooks/escalation \
  -H "Content-Type: application/json" \
  -H "x-webhook-signature: $SIGNATURE" \
  -d "$PAYLOAD"

typescript
import pino from "pino";

const logger = pino({ level: "info" });

app.post("/webhooks/escalation", (req, res) => {
  const conversationId = req.body?.data?.conversationId || "unknown";
  const childLogger = logger.child({ conversationId, event: req.body?.event });

  if (!verifyWebhookSignature(JSON.stringify(req.body), req.headers["x-webhook-signature"] as string)) {
    childLogger.warn("Invalid webhook signature");
    return res.status(401).json({ error: "Invalid signature" });
  }

  childLogger.info("Webhook received");
  res.status(200).json({ received: true });

  createTicket(req.body as WebhookPayload)
    .then((ticket) => {
      childLogger.info({ ticketId: ticket.id }, "Ticket created successfully");
    })
    .catch((err) => {
      childLogger.error({ err }, "Ticket creation failed");
    });
});

typescript
app.get("/health", async (_, res) => {
  const checks: Record<string, "ok" | "error"> = {};

  try {
    await fetch(`${HELPDESK_API_URL}/health`, {
      headers: { Authorization: `Bearer ${HELPDESK_API_KEY}` },
      signal: AbortSignal.timeout(3000),
    });
    checks.helpdesk = "ok";
  } catch {
    checks.helpdesk = "error";
  }

  try {
    await redis.ping();
    checks.redis = "ok";
  } catch {
    checks.redis = "error";
  }

  const allHealthy = Object.values(checks).every((v) => v === "ok");
  res.status(allHealthy ? 200 : 503).json({ status: allHealthy ? "ok" : "degraded", checks });
});