Crear webhook de la subcuenta

Este endpoint permite registrar automáticamente la primera URL de webhook para una subcuenta recién creada.

Regla de uso único

Esta ruta fue diseñada exclusivamente para la configuración inicial de la subcuenta. Solo permite guardar el primer webhook. Si la subcuenta ya tiene un webhook configurado, la API devolverá un error.

---

Endpoint

• Método: POST

URL del endpoint

https://api.xgateglobal.com/webhook/subaccount

---

Solicitud

Encabezados obligatorios

Encabezado	Valor	Descripción
Authorization	Bearer <tu_token>	Token JWT de autenticación de la subcuenta.

Cuerpo de la solicitud

Parámetro	Tipo	Validación	Descripción
name	string	Obligatorio	Un nombre interno de identificación para el webhook (por ejemplo, "Primer webhook").
externalWebhookUrl	string	Obligatorio	La URL completa de su servidor que recibirá los datos enviados por XGate vía POST.

Ejemplo de payload

{
    "externalWebhookUrl": "https://su-empresa.com/api/webhooks/subaccount/xgate",
    "name": "Primer webhook"
}

---

Respuestas

Éxito (200 OK)

La URL de notificación se registró y ya está activa para la subcuenta.

{
    "message": "Primer webhook registrado con éxito"
}

Errores comunes

Estado	Mensaje	Motivo probable
400	Bad Request	• Esta funcionalidad no está disponible para su cuenta: la cuenta que realiza la solicitud no es una subcuenta válida para este flujo. • Esta funcionalidad solo permite guardar el primer webhook de su cuenta: la subcuenta ya tiene un webhook registrado. Esta ruta solo funciona cuando la lista de webhooks está vacía.
401	Unauthorized	• Token inválido o caducado. • Encabezado inválido o no proporcionado. • IP no permitido.
500	Internal Server Error	Error interno del servidor. Contacte con soporte.

---

Cómo usar

Casos de uso comunes

1. Automatización de configuración (onboarding): Cuando su cuenta principal (master) crea una subcuenta para un nuevo cliente corporativo, puede programar su sistema para iniciar sesión inmediatamente en la subcuenta recién creada y activar este endpoint. Esto garantiza que la subcuenta nazca lista para notificar a su gateway interno sobre los pagos, sin necesidad de intervención manual en el panel.

---

Integración

A continuación se muestra un ejemplo simple de cómo implementar esta llamada con Node.js. Recuerde usar las credenciales de la subcuenta para obtener el token de autorización.

Node.js

El ejemplo de integración utiliza la biblioteca Axios para realizar la solicitud HTTP.

Instalando Axios:

npm install axios

Ejemplo en JavaScript:

const axios = require("axios");

(async () => {
    // ATENCIÓN: use el correo electrónico y la contraseña de la SUBCUENTA para generar el token de esta acción
    const emailSubcuenta = "admin@subcuenta.com";
    const passwordSubcuenta = "••••••";

    try {
        const url_api = "https://api.xgateglobal.com";
        
        // 1. Obtener el token de autenticación de la subcuenta
        const login = await axios.post(`${url_api}/auth/token`, { 
            email: emailSubcuenta, 
            password: passwordSubcuenta 
        });
        
        // 2. Configurar el primer webhook
        const webhookData = {
            externalWebhookUrl: "https://api.su-empresa.com/webhooks/xgate/subaccount-1",
            name: "Webhook principal - Subcuenta 1"
        };

        const { data } = await axios.post(`${url_api}/webhook/subaccount`, webhookData, {
            headers: {
                "Authorization": `Bearer ${login.data.token}`,
                "Content-Type": "application/json"
            }
        });
        
        console.log("Respuesta:", data); 
        // Esperado: { message: 'Primer webhook registrado con éxito' }

    } catch (error) {
        console.error("Error al registrar webhook:", error.response ? JSON.stringify(error.response.data, null, 2) : error.message);
    }
})();