Configuración de los Webhooks

Los webhooks permiten a Sangho notificar a su servidor en tiempo real cuando se producen eventos en su cuenta. Puede crear y gestionar sus endpoints desde el panel o mediante la API de Webhooks.

Crear un endpoint desde el panel

• 1. Vaya a Panel → Desarrolladores → Webhooks.
• 2. Haga clic en Añadir un endpoint.
• 3. Introduzca la URL HTTPS de su servidor.
• 4. Seleccione los eventos que desea escuchar (o Todos los eventos).
• 5. Haga clic en Crear y copie el webhook_secret que se muestra una sola vez.

Requisitos del endpoint

• URL HTTPS válida (se rechaza HTTP, salvo localhost en el Sandbox).
• Respuesta HTTP 200 en un máximo de 30 segundos.
• Se ignora el cuerpo de la respuesta: solo cuenta el código HTTP.
• Endpoint accesible públicamente desde internet.

Responda 200 de inmediato

Responda siempre con HTTP 200 de inmediato, incluso si el procesamiento de negocio falla. Gestione los errores en segundo plano para evitar reentregas innecesarias. Consulte la guía de Idempotencia para la gestión de duplicados.

¿Está clara la configuración?

UtileÀ améliorer

Endpoint mínimo (Express)

Node JSPython

javascriptCopier

const express = require('express');
const app = express();


// IMPORTANT : utiliser express.raw, pas express.json
app.post(
  '/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const event = JSON.parse(req.body);
    console.log('Événement reçu :', event.type);


    // Traiter en arrière-plan, répondre immédiatement
    processEvent(event).catch(console.error);


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

Política de reintentos

Si su endpoint no responde 200 en 30 segundos, Sangho reintenta la entrega 10 veces con un retraso exponencial.

Intento	Retraso acumulado
1	Inmediato
2	+5 min
3	+15 min
4	+30 min
5	+1 h
6	+2 h
7	+4 h
8	+8 h
9	+16 h
10	+24 h y luego +48 h

Probar un endpoint

Desde la ficha de un endpoint en el panel, haga clic en Enviar un evento de prueba. Seleccione el tipo de evento y Sangho envía una carga útil real a su endpoint. También puede utilizar la API:

Túnel local para las pruebas

Para probar su endpoint en desarrollo local, utilice ngrok o localtunnel para exponer su servidor local mediante una URL HTTPS pública.

¿Está bien explicada la política de reintentos?

UtileÀ améliorer

Enviar un evento de prueba (API)

cURLNode JSPython

bashCopier

curl -X POST https://api.sangho.ga/v1/webhooks/wh_xxx/test/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "event_type": "payment_intent.succeeded" }'

Response200 OK — Evento de prueba enviado

Sangho envía una carga útil real a su endpoint. Compruebe sus registros de entrega para confirmar la recepción.

jsonCopier

{
  "id": "evt_test_xxxxxxxxxxxx",
  "object": "event",
  "type": "payment_intent.succeeded",
  "livemode": false,
  "test": true,
  "created_at": "2026-03-01T10:00:00Z"
}