¿Qué son los Webhooks?

Los webhooks son notificaciones HTTP automáticas que el sistema envía a tu servidor cada vez que ocurre un evento importante, como recibir un mensaje SMS o de WhatsApp.

Esta función solo se activa con eventos entrantes: SMS recibidos, mensajes de WhatsApp, respuestas USSD y notificaciones de Android.

---

Casos de Uso

• Guardar mensajes recibidos en tu propia base de datos
• Crear tickets de soporte automáticos al recibir un mensaje
• Integrar con tu CRM (registrar contactos, actualizar estados)
• Enviar alertas a Telegram, Slack o correo cuando llega un mensaje
• Generar reportes automáticos de actividad
• Sincronizar conversaciones con sistemas externos
• Activar flujos de automatización en herramientas como Zapier o n8n

---

¿Cómo Funciona?

Cuando se recibe un evento (ej: un SMS entrante), el sistema hace un POST automático a la URL que configuraste, enviando toda la información del mensaje en formato JSON.

---

Estructura de los Datos (Payload)

Cada payload incluye un tipo (type) y los datos del evento. A continuación puedes ver la estructura según el tipo de mensaje:

SMS Recibido

{
    "type": "sms",               // Tipo de evento
    "data": {
        "id": "123",             // ID único del mensaje en el sistema
        "rid": "456",            // ID de referencia
        "sim": 1,                // Ranura SIM que recibió el mensaje (1 o 2)
        "phone": "+58412...",    // Número del remitente
        "message": "Hola...",    // Contenido del mensaje
        "timestamp": 1679900000  // Fecha/hora en formato Unix
    },
    "secret": "tu_clave_secreta" // Clave para verificar autenticidad
}

WhatsApp Recibido

{
    "type": "whatsapp",          // Tipo de evento
    "data": {
        "id": "789",             // ID único del mensaje
        "wid": "xxx@s.whatsapp.net", // ID de la cuenta WhatsApp receptora
        "phone": "+58414...",    // Número del remitente
        "message": "Hola...",    // Contenido del mensaje
        "timestamp": 1679900000  // Fecha/hora en formato Unix
    },
    "secret": "tu_clave_secreta"
}

Respuesta USSD

{
    "type": "ussd",              // Tipo de evento
    "data": {
        "id": "101",             // ID único
        "sim": 1,                // Ranura SIM
        "code": "*123#",         // Código USSD ejecutado
        "response": "Saldo: $5", // Respuesta del operador
        "timestamp": 1679900000
    },
    "secret": "tu_clave_secreta"
}

Notificación Android

{
    "type": "notification",      // Tipo de evento
    "data": {
        "id": "201",             // ID único
        "title": "WhatsApp",     // App que generó la notificación
        "message": "Nuevo msg",  // Contenido de la notificación
        "timestamp": 1679900000
    },
    "secret": "tu_clave_secreta"
}

---

Ejemplo de Código (PHP)

Tu servidor recibe los datos via POST en formato JSON. Aquí un ejemplo completo de cómo procesarlos:

<?php
// 1. Recibir los datos JSON del webhook
$payload = json_decode(file_get_contents("php://input"), true);

// 2. Verificar la autenticidad con tu clave secreta
$miSecreto = "tu_clave_secreta_aqui";
if (!isset($payload["secret"]) || !hash_equals($miSecreto, $payload["secret"])) {
    http_response_code(403);
    die("No autorizado");
}

// 3. Procesar según el tipo de evento
$tipo = $payload["type"];
$data = $payload["data"];

switch ($tipo) {
    case "sms":
        // SMS recibido
        $telefono = $data["phone"];
        $mensaje  = $data["message"];
        // Guardar en base de datos, enviar alerta, etc.
        break;

    case "whatsapp":
        // Mensaje de WhatsApp recibido
        $telefono = $data["phone"];
        $mensaje  = $data["message"];
        break;

    case "ussd":
        // Respuesta USSD
        $codigo   = $data["code"];
        $respuesta = $data["response"];
        break;

    case "notification":
        // Notificación de Android
        $titulo  = $data["title"];
        $mensaje = $data["message"];
        break;
}

// 4. Responder con 200 OK para confirmar recepción
http_response_code(200);
echo "OK";