Webhooks y Acciones

Que son los Webhooks

Los webhooks son notificaciones HTTP que WhatsBoost envia automaticamente a una URL de tu servidor cada vez que ocurre un evento relevante: un SMS recibido, un mensaje de WhatsApp enviado, una respuesta USSD, etc.

En lugar de hacer polling constante a la API para comprobar si hay nuevos eventos, configuras una URL y WhatsBoost te notifica en tiempo real mediante una peticion HTTP POST.

Propiedades de un webhook

Eventos disponibles

Puedes suscribir cada webhook a uno o varios eventos. Puedes seleccionar uno o varios eventos al crear el webhook (por ejemplo "sms,whatsapp").

Payload del webhook

Cada notificacion contiene un JSON con la estructura secret + type + data. El campo secret coincide con el token SHA1 que se genero al crear el webhook, permitiendote verificar la autenticidad.

Payload SMS recibido

{
  "secret": "webhook_sha1_secret",
  "type": "sms",
  "data": {
    "id": 1234,
    "rid": 5678,
    "sim": 1,
    "device": "device-uuid",
    "phone": "+34612345678",
    "message": "Contenido del mensaje",
    "timestamp": 1711108200
  }
}

Payload WhatsApp recibido

{
  "secret": "webhook_sha1_secret",
  "type": "whatsapp",
  "data": {
    "id": 1234,
    "wid": "+34612345678",
    "phone": "+34612345678",
    "message": "Contenido del mensaje",
    "attachment": "https://site/uploads/whatsapp/received/imagen.jpg",
    "timestamp": 1711108200
  }
}

Payload USSD respuesta

{
  "secret": "webhook_sha1_secret",
  "type": "ussd",
  "data": {
    "id": 1234,
    "sim": 1,
    "device": "device-uuid",
    "code": "*123#",
    "response": "Your balance is...",
    "timestamp": 1711108200
  }
}

Configuracion tecnica del envio

Cuando ocurre un evento, WhatsBoost envia la notificacion al webhook con la siguiente configuracion HTTP:

Verificar autenticidad

Cada payload contiene un campo secret que coincide con el token SHA1 generado automaticamente al crear el webhook en el Dashboard. Siempre debes verificar este campo antes de procesar los datos para asegurarte de que la peticion proviene de WhatsBoost y no de un tercero.

Implementar receptor

A continuacion se muestran ejemplos completos de como implementar un receptor de webhooks en PHP y Node.js.

<?php
// webhook-receiver.php
// Tu secret del webhook (copiado del Dashboard)
$miSecret = "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2";

// 1. Leer el body de la peticion POST
$payload = $_POST;

// 2. Verificar autenticidad
if (empty($payload["secret"]) || $payload["secret"] !== $miSecret) {
    http_response_code(403);
    echo json_encode(["error" => "Secret invalido"]);
    exit;
}

// 3. Decodificar datos
$type = $payload["type"] ?? "";
$data = json_decode($payload["data"] ?? "{}", true);

// 4. Procesar segun el tipo de evento
switch ($type) {
    case "sms":
        // SMS recibido o enviado
        $phone   = $data["phone"] ?? "";
        $message = $data["message"] ?? "";
        $device  = $data["device"] ?? "";
        // Tu logica: guardar en DB, notificar CRM, etc.
        error_log("SMS de $phone: $message");
        break;

    case "whatsapp":
        // WhatsApp recibido o enviado
        $phone      = $data["phone"] ?? "";
        $message    = $data["message"] ?? "";
        $attachment = $data["attachment"] ?? null;
        // Tu logica: responder automaticamente, actualizar ticket, etc.
        error_log("WhatsApp de $phone: $message");
        break;

    case "ussd":
        // Respuesta USSD
        $code     = $data["code"] ?? "";
        $response = $data["response"] ?? "";
        // Tu logica: parsear saldo, actualizar registro, etc.
        error_log("USSD $code: $response");
        break;

    default:
        error_log("Tipo de webhook desconocido: $type");
        break;
}

// 5. Responder 200 rapidamente
http_response_code(200);
echo json_encode(["ok" => true]);

// webhook-receiver.js (Express)
const express = require("express");
const app = express();

app.use(express.urlencoded({ extended: true }));

const MI_SECRET = "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2";

app.post("/webhook", (req, res) => {
  // 1. Verificar autenticidad
  if (!req.body.secret || req.body.secret !== MI_SECRET) {
    return res.status(403).json({ error: "Secret invalido" });
  }

  // 2. Responder 200 inmediatamente
  res.status(200).json({ ok: true });

  // 3. Procesar de forma asincrona
  const type = req.body.type || "";
  let data;
  try {
    data = JSON.parse(req.body.data || "{}");
  } catch (e) {
    data = {};
  }

  switch (type) {
    case "sms":
      console.log(`SMS de $${data.phone}: $${data.message}`);
      // Tu logica aqui
      break;

    case "whatsapp":
      console.log(`WhatsApp de $${data.phone}: $${data.message}`);
      // Tu logica aqui
      break;

    case "ussd":
      console.log(`USSD $${data.code}: $${data.response}`);
      // Tu logica aqui
      break;

    default:
      console.warn(`Tipo desconocido: $${type}`);
  }
});

app.listen(3000, () => console.log("Receptor webhook en puerto 3000"));

Probar webhooks

WhatsBoost proporciona un endpoint de prueba que envia datos de ejemplo a tu URL receptor para verificar que todo funciona correctamente antes de pasar a produccion.

Endpoint de prueba

POST //whatsboost.netrequests

Ejemplo con cURL

curl -X POST //whatsboost.netrequests \
  -d "type=trigger" \
  -d "secret=TU_WEBHOOK_SECRET" \
  -d "type=sms" \
  -d "url=https://tu-servidor.com/webhook"

WhatsBoost enviara un payload de ejemplo a la URL indicada con datos ficticios. Comprueba los logs de tu servidor para verificar que la peticion llego correctamente y que la verificacion del secret funciona.

Acciones (Action Hooks)

Las Acciones son un mecanismo diferente a los webhooks. Mientras que los webhooks envian un POST con el payload completo, las acciones realizan una peticion HTTP GET a una URL que tu defines con variables dinamicas que se sustituyen automaticamente.

Propiedades de una accion

Variables disponibles en la URL

Ejemplo de URL plantilla

https://api.example.com/hook?phone={{phone}}&msg={{message}}&date={{date.now}}

Cuando se reciba un SMS del numero +34612345678 con el texto "Hola mundo", WhatsBoost realizara un GET a:

https://api.example.com/hook?phone=%2B34612345678&msg=Hola%20mundo&date=March%2022%2C%202026

Diferencias clave: Webhooks vs Acciones

Prompt IA: Integracion de webhooks

Copia este prompt en ChatGPT, Claude, Gemini o cualquier asistente de IA para que te ayude a implementar un receptor de webhooks de WhatsBoost.

Eres un desarrollador backend experto. Necesito implementar un receptor de webhooks para WhatsBoost.

INFORMACION DEL SISTEMA:
- WhatsBoost envia peticiones HTTP POST con Content-Type application/x-www-form-urlencoded.
- Timeout de 5 segundos. Debo responder 200 rapidamente y procesar de forma asincrona.
- Cada payload contiene: secret (string SHA1), type (sms|whatsapp|ussd), data (JSON string).

PAYLOADS POR TIPO:
- SMS: data contiene id, rid, sim, device, phone, message, timestamp
- WhatsApp: data contiene id, wid, phone, message, attachment (url o null), timestamp
- USSD: data contiene id, sim, device, code, response, timestamp

REQUISITOS:
1. Verificar el secret contra mi token almacenado. Si no coincide, responder 403.
2. Parsear el campo "data" como JSON.
3. Segun el tipo, ejecutar la logica correspondiente.
4. Responder HTTP 200 lo antes posible.
5. Implementar logging para debug.
6. Manejar errores sin romper el flujo.

Mi stack es: [INDICA TU STACK AQUI]
El secret de mi webhook es: [TU SECRET AQUI]
Quiero que al recibir un WhatsApp, [DESCRIBE TU LOGICA AQUI].