Saltar al contenido principal
Imagen de portada de Webhook
Los webhooks proporcionan notificaciones en tiempo real cuando ocurren eventos específicos en tu cuenta de Dodo Payments. Utiliza webhooks para automatizar flujos de trabajo, actualizar tu base de datos, enviar notificaciones y mantener tus sistemas sincronizados.
Nuestra implementación de webhook sigue la especificación de Standard Webhooks, asegurando compatibilidad con las mejores prácticas de la industria y bibliotecas de webhook existentes.

Características clave

Entrega en tiempo real

Recibe notificaciones instantáneas cuando ocurren eventos

Seguro por defecto

Verificación de firma HMAC SHA256 incluida

Reintentos automáticos

Lógica de reintento incorporada con retroceso exponencial

Filtrado de eventos

Suscríbete solo a los eventos que necesitas

Comenzando

1

Acceder a la configuración de Webhook

Navega al panel de DodoPayments y ve a Settings > Webhooks.
2

Crear un endpoint de Webhook

Haz clic en Add Webhook para crear un nuevo endpoint de webhook.
Agregar Webhook
3

Agregar URL de Endpoint

Ingresa la URL donde deseas recibir eventos de webhook.
4

Seleccionar eventos a recibir

Elige los eventos específicos a los que tu endpoint de webhook debe escuchar seleccionándolos de la lista de eventos.
Solo los eventos seleccionados activarán webhooks a tu endpoint, ayudándote a evitar tráfico y procesamiento innecesarios.
5

Obtener clave secreta

Obtén tu Secret Key de la página de configuración. La usarás para verificar la autenticidad de los webhooks recibidos.
Mantén tu clave secreta de webhook segura y nunca la expongas en código del lado del cliente o en repositorios públicos.
6

Rotar secreto (opcional)

Si es necesario, puedes rotar tu secreto de webhook para mejorar la seguridad. Haz clic en el botón Rotar secreto en la configuración de tu webhook.
Rotar el secreto lo expirará y lo reemplazará por uno nuevo. El antiguo secreto solo será válido durante las próximas 24 horas. Después, intentar verificar con el antiguo secreto fallará.
Utiliza la rotación de secretos periódicamente o inmediatamente si sospechas que tu secreto actual ha sido comprometido.

Configurando eventos suscritos

Puedes configurar qué eventos específicos deseas recibir para cada endpoint de webhook.

Accediendo a la configuración de eventos

1

Navegar a los detalles del Webhook

Ve a tu panel de Dodo Payments y navega a Settings > Webhooks.
2

Seleccionar tu endpoint

Haz clic en el endpoint de webhook que deseas configurar.
3

Abrir configuración de eventos

En la página de detalles del webhook, verás una sección de “Eventos suscritos”. Haz clic en el botón Editar para modificar tus suscripciones de eventos.

Gestionando suscripciones de eventos

1

Ver eventos disponibles

La interfaz muestra todos los eventos de webhook disponibles organizados en una estructura jerárquica. Los eventos están agrupados por categoría (por ejemplo, dispute, payment, subscription).
2

Buscar y filtrar

Usa la barra de búsqueda para encontrar rápidamente eventos específicos escribiendo nombres de eventos o palabras clave.
3

Seleccionar eventos

Marca las casillas junto a los eventos que deseas recibir. Puedes:
  • Seleccionar sub-eventos individuales (por ejemplo, dispute.accepted, dispute.challenged)
  • Seleccionar eventos principales para recibir todos los sub-eventos relacionados
  • Mezclar y combinar eventos específicos según tus necesidades
4

Revisar detalles del evento

Pasa el cursor sobre el ícono de información (ⓘ) junto a cada evento para ver una descripción de cuándo se activa ese evento.
5

Guardar configuración

Haz clic en Guardar para aplicar tus cambios, o Cancelar para descartar modificaciones.
Si deseleccionas todos los eventos, tu endpoint de webhook no recibirá ninguna notificación. Asegúrate de seleccionar al menos los eventos que tu aplicación necesita para funcionar correctamente.

Entrega de Webhook

Timeouts

Los webhooks tienen una ventana de tiempo de espera de 15 segundos tanto para operaciones de conexión como de lectura. Asegúrate de que tu endpoint responda rápidamente para evitar timeouts.
Procesa los webhooks de manera asíncrona reconociendo la recepción de inmediato con un código de estado 200, y luego maneja el procesamiento real en segundo plano.

Reintentos automáticos

Si falla la entrega de un webhook, Dodo Payments reintenta automáticamente con retroceso exponencial para evitar abrumar tu sistema.
IntentoRetrasoDescripción
1InmediatamenteEl primer reintento ocurre de inmediato
25 segundosSegundo intento después de un breve retraso
35 minutosTercer intento con un retroceso aumentado
430 minutosCuarto intento continuando el retroceso
52 horasQuinto intento con un retraso extendido
65 horasSexto intento con un retraso más largo
710 horasSéptimo intento con el retraso máximo
810 horasÚltimo intento - webhook marcado como fallido si no tiene éxito
Máximo de 8 intentos de reintento por evento de webhook. Por ejemplo, si un webhook falla tres veces antes de tener éxito, el tiempo total de entrega es de aproximadamente 35 minutos y 5 segundos desde el primer intento.
Utiliza el panel de Dodo Payments para reintentar manualmente mensajes individuales o recuperar en bloque todos los mensajes fallidos en cualquier momento.

Idempotencia

Cada evento de webhook incluye un encabezado único webhook-id. Usa este identificador para implementar idempotencia y prevenir el procesamiento duplicado.
// Example: Storing webhook IDs to prevent duplicate processing
const processedWebhooks = new Set();

app.post('/webhook', (req, res) => {
  const webhookId = req.headers['webhook-id'];
  
  if (processedWebhooks.has(webhookId)) {
    return res.status(200).json({ received: true });
  }
  
  processedWebhooks.add(webhookId);
  // Process the webhook...
});
Siempre implementa verificaciones de idempotencia. Debido a los reintentos, puedes recibir el mismo evento múltiples veces.

Orden de eventos

Los eventos de webhook pueden llegar fuera de orden debido a reintentos o condiciones de red. Diseña tu sistema para manejar eventos en cualquier secuencia.
Recibirás la última carga útil en el momento de la entrega, independientemente de cuándo se emitió originalmente el evento de webhook.

Asegurando Webhooks

Para garantizar la seguridad de tus webhooks, siempre valida las cargas útiles y utiliza HTTPS.

Verificando firmas

Cada solicitud de webhook incluye un encabezado webhook-signature, una firma HMAC SHA256 de la carga útil del webhook y la marca de tiempo, firmada con tu clave secreta.

Verificación de SDK (recomendada)

Todos los SDK oficiales incluyen ayudantes integrados para validar y analizar de manera segura los webhooks entrantes. Hay dos métodos disponibles:
  • unwrap(): Verifica firmas utilizando tu clave secreta de webhook
  • unsafe_unwrap(): Analiza cargas útiles sin verificación
Proporciona tu secreto de webhook a través de DODO_PAYMENTS_WEBHOOK_KEY al inicializar el cliente de Dodo Payments.
import DodoPayments from 'dodopayments';
import express from 'express';

const app = express();
app.use(express.raw({ type: 'application/json' }));

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
});

app.post('/webhook', async (req, res) => {
  try {
    const unwrapped = client.webhooks.unwrap(req.body.toString(), {
      headers: {
        'webhook-id': req.headers['webhook-id'] as string,
        'webhook-signature': req.headers['webhook-signature'] as string,
        'webhook-timestamp': req.headers['webhook-timestamp'] as string,
      },
    });
    res.json({ received: true });
  } catch (error) {
    res.status(401).json({ error: 'Invalid signature' });
  }
});

Verificación manual (alternativa)

Si no estás utilizando un SDK, puedes verificar las firmas tú mismo siguiendo la especificación de Standard Webhooks:
  1. Construye el mensaje firmado concatenando webhook-id, webhook-timestamp, y la cadena exacta sin procesar payload, separadas por puntos (.).
  2. Calcula el HMAC SHA256 de esa cadena utilizando tu clave secreta de webhook del panel.
  3. Compara la firma calculada con el encabezado webhook-signature. Si coinciden, el webhook es auténtico.
Seguimos la especificación de Standard Webhooks. Puedes usar sus bibliotecas para verificar firmas: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. Para formatos de carga útil de eventos, consulta la Carga útil de Webhook.

Respondiendo a Webhooks

  • Tu manejador de webhook debe devolver un 2xx status code para reconocer la recepción del evento.
  • Cualquier otra respuesta se tratará como un fallo, y el webhook será reintentado.

Mejores prácticas

Siempre utiliza URLs HTTPS para los endpoints de webhook. Los endpoints HTTP son vulnerables a ataques de intermediarios y exponen tus datos de webhook.
Devuelve un código de estado 200 inmediatamente al recibir el webhook. Procesa el evento de manera asíncrona para evitar timeouts.
app.post('/webhook', async (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).json({ received: true });
  
  // Process asynchronously
  processWebhookAsync(req.body).catch(console.error);
});
Implementa idempotencia utilizando el encabezado webhook-id para procesar de manera segura el mismo evento múltiples veces sin efectos secundarios.
Almacena tu secreto de webhook de manera segura utilizando variables de entorno o un gestor de secretos. Nunca cometas secretos en el control de versiones.

Estructura de la carga útil de Webhook

Entender la estructura de la carga útil de webhook te ayuda a analizar y procesar eventos correctamente.

Formato de solicitud

POST /your-webhook-url
Content-Type: application/json

Encabezados

webhook-id
string
required
Identificador único para este evento de webhook. Úsalo para verificaciones de idempotencia.
webhook-signature
string
required
Firma HMAC SHA256 para verificar la autenticidad del webhook.
webhook-timestamp
string
required
Marca de tiempo Unix (en segundos) cuando se envió el webhook.

Cuerpo de la solicitud

business_id
string
required
Tu identificador de negocio de Dodo Payments.
type
string
required
Tipo de evento que activó este webhook (por ejemplo, payment.succeeded, subscription.created).
timestamp
string
required
Marca de tiempo formateada en ISO 8601 de cuándo ocurrió el evento.
data
object
required
Carga útil específica del evento que contiene información detallada sobre el evento.

Ejemplo de carga útil

{
  "business_id": "string",
  "type": "payment.succeeded | payment.failed |...",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "payload_type": "Payment | Subscription | Refund | Dispute | LicenseKey",
    // ... event-specific fields (see below)
  }
}

Probando Webhooks

Puedes probar tu integración de webhook directamente desde el panel de Dodo Payments para asegurarte de que tu endpoint esté funcionando correctamente antes de entrar en producción.
Detalles del Endpoint

Accediendo a la interfaz de prueba

1

Navegar a Webhooks

Ve a tu panel de Dodo Payments y navega a Settings > Webhooks.
2

Seleccionar tu endpoint

Haz clic en tu endpoint de webhook para acceder a su página de detalles.
3

Abrir pestaña de prueba

Haz clic en la pestaña Pruebas para acceder a la interfaz de prueba de webhook.

Probando tu Webhook

La interfaz de prueba proporciona una forma integral de probar tu endpoint de webhook:
1

Seleccionar tipo de evento

Usa el menú desplegable para seleccionar el tipo de evento específico que deseas probar (por ejemplo, payment.succeeded, payment.failed, etc.).
El menú desplegable contiene todos los tipos de eventos de webhook disponibles que tu endpoint puede recibir.
2

Revisar esquema y ejemplo

La interfaz muestra tanto el Esquema (estructura de datos) como el Ejemplo (carga útil de muestra) para el tipo de evento seleccionado.
3

Enviar evento de prueba

Haz clic en el botón Enviar ejemplo para enviar un webhook de prueba a tu endpoint.
Importante: Los mensajes fallidos enviados a través de la interfaz de prueba no serán reintentados. Esto es solo para fines de prueba.

Verificando tu prueba

1

Verifica tu endpoint

Monitorea los registros de tu endpoint de webhook para confirmar que se recibió el evento de prueba.
2

Verificar firma

Asegúrate de que tu verificación de firma esté funcionando correctamente con la carga útil de prueba.
3

Probar respuesta

Confirma que tu endpoint devuelve un código de estado 2xx para reconocer la recepción.

Ejemplo de implementación

Aquí hay una implementación completa de Express.js que muestra la verificación y el manejo de webhooks:
import { Webhook } from "standardwebhooks";
import express from "express";

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

const webhook = new Webhook(process.env.DODO_WEBHOOK_SECRET);

app.post('/webhook/dodo-payments', async (req, res) => {
  try {
    // Extract webhook headers
    const webhookHeaders = {
      "webhook-id": req.headers["webhook-id"] as string,
      "webhook-signature": req.headers["webhook-signature"] as string,
      "webhook-timestamp": req.headers["webhook-timestamp"] as string,
    };

    // Verify the webhook signature
    const payload = JSON.stringify(req.body);
    await webhook.verify(payload, webhookHeaders);
    
    // Acknowledge receipt immediately
    res.status(200).json({ received: true });
    
    // Process webhook asynchronously
    processWebhookAsync(req.body).catch(console.error);
    
  } catch (error) {
    console.error('Webhook verification failed:', error);
    res.status(400).json({ error: 'Invalid signature' });
  }
});

async function processWebhookAsync(data: any) {
  // Handle the webhook event based on type
  switch (data.type) {
    case 'payment.succeeded':
      await handlePaymentSucceeded(data);
      break;
    case 'subscription.created':
      await handleSubscriptionCreated(data);
      break;
    // Add more event handlers...
  }
}
Prueba tu manejador de webhook a fondo utilizando la interfaz de prueba del panel antes de procesar eventos de producción. Esto ayuda a identificar y solucionar problemas temprano.

Configuraciones avanzadas

La pestaña de Configuraciones avanzadas proporciona opciones de configuración adicionales para ajustar el comportamiento de tu endpoint de webhook.

Limitación de tasa (Throttling)

Controla la tasa a la que se entregan los eventos de webhook a tu endpoint para evitar abrumar tu sistema.
1

Acceder a la configuración de límite de tasa

En la pestaña Avanzado, localiza la sección “Límite de tasa (throttling)”.
2

Configurar límite de tasa

Haz clic en el botón Editar para modificar la configuración del límite de tasa.
Por defecto, los webhooks tienen “Sin límite de tasa” aplicado, lo que significa que los eventos se entregan tan pronto como ocurren.
3

Establecer límites

Configura tu límite de tasa deseado para controlar la frecuencia de entrega de webhooks y prevenir sobrecargas en el sistema.
Utiliza la limitación de tasa cuando tu manejador de webhook necesite tiempo para procesar eventos o cuando desees agrupar múltiples eventos juntos.

Encabezados personalizados

Agrega encabezados HTTP personalizados a todas las solicitudes de webhook enviadas a tu endpoint. Esto es útil para autenticación, enrutamiento o agregar metadatos a tus solicitudes de webhook.
1

Agregar encabezado personalizado

En la sección “Encabezados personalizados”, ingresa una Clave y un Valor para tu encabezado personalizado.
2

Agregar múltiples encabezados

Haz clic en el botón + para agregar encabezados personalizados adicionales según sea necesario.
3

Guardar configuración

Tus encabezados personalizados se incluirán en todas las solicitudes de webhook a este endpoint.

Transformaciones

Las transformaciones te permiten modificar la carga útil de un webhook y redirigirla a una URL diferente. Esta poderosa función te permite:
  • Modificar la estructura de la carga útil antes de procesarla
  • Enrutar webhooks a diferentes endpoints según el contenido
  • Agregar o eliminar campos de la carga útil
  • Transformar formatos de datos
1

Habilitar transformaciones

Activa el interruptor Habilitado para activar la función de transformación.
2

Configurar transformación

Haz clic en Editar transformación para definir tus reglas de transformación.
Puedes usar JavaScript para transformar la carga útil del webhook y especificar una URL de destino diferente.
3

Probar transformación

Utiliza la interfaz de prueba para verificar que tu transformación funcione correctamente antes de entrar en producción.
Las transformaciones pueden impactar significativamente el rendimiento de entrega de webhooks. Prueba a fondo y mantén la lógica de transformación simple y eficiente.
Las transformaciones son particularmente útiles para:
  • Convertir entre diferentes formatos de datos
  • Filtrar eventos según criterios específicos
  • Agregar campos computados a la carga útil
  • Enrutar eventos a diferentes microservicios

Monitoreo de registros de Webhook

La pestaña de Registros proporciona visibilidad integral sobre el estado de entrega de tus webhooks, permitiéndote monitorear, depurar y gestionar eventos de webhook de manera efectiva.
Registros

Monitoreo de actividad

La pestaña de Actividad proporciona información en tiempo real sobre el rendimiento de entrega de tus webhooks con análisis visual.
Actividad

Alertas por correo electrónico

Mantente informado sobre la salud de tus webhooks con notificaciones automáticas por correo electrónico. Cuando las entregas de webhooks comienzan a fallar o tu endpoint deja de responder, recibirás alertas por correo electrónico para que puedas abordar rápidamente los problemas y mantener tus integraciones funcionando sin problemas.
Configuración de alertas de Webhook mostrando la configuración de notificaciones por correo electrónico

Habilitar alertas por correo electrónico

1

Navegar a la configuración de alertas

Ve a tu panel de Dodo Payments y navega a Panel → Webhooks → Alertas.
2

Habilitar notificaciones por correo electrónico

Activa Notificaciones por correo electrónico para comenzar a recibir alertas sobre problemas de entrega de webhooks.
3

Configurar dirección de correo electrónico

Ingresa la dirección de correo electrónico donde deseas recibir alertas de webhook. Enviaremos notificaciones a esta dirección cuando ocurran ciertos eventos con tu configuración de webhooks, como problemas de entrega que puedan afectar tus integraciones.
Habilita alertas por correo electrónico para detectar problemas de entrega de webhooks temprano y mantener integraciones confiables. Serás notificado cuando las entregas fallen o tu endpoint se vuelva no receptivo.

Desplegar en plataformas en la nube

¿Listo para desplegar tu manejador de webhook en producción? Proporcionamos guías específicas de la plataforma para ayudarte a desplegar webhooks en proveedores de nube populares con las mejores prácticas para cada plataforma.
Cada guía de plataforma incluye configuración del entorno, verificación de firma y pasos de despliegue específicos para ese proveedor.