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 webhooks sigue la especificación de Standard Webhooks, lo que garantiza compatibilidad con las mejores prácticas de la industria y las bibliotecas de webhooks existentes.

Características clave

Real-time Delivery

Recibe notificaciones instantáneas cuando ocurren eventos

Secure by Default

Verificación de firma HMAC SHA256 incluida

Automatic Retries

Lógica de reintentos integrada con retroceso exponencial

Event Filtering

Suscríbete únicamente a los eventos que necesitas

Comenzando

1

Access Webhook Settings

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

Create Webhook Endpoint

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

Add Endpoint URL

Ingresa la URL donde deseas recibir los eventos de webhook.
4

Select Events to Receive

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

Get Secret Key

Obtén tu Secret Key de webhook desde la página de configuración. Lo 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 ni repositorios públicos.
6

Rotate Secret (Optional)

Si es necesario, puedes rotar tu secreto de webhook para reforzar la seguridad. Haz clic en el botón Rotate Secret en los ajustes de tu webhook.
Rotar el secreto lo expirará y lo reemplazará por uno nuevo. El secreto anterior solo será válido durante las siguientes 24 horas. Después de eso, intentar verificar con el secreto antiguo fallará.
Usa la rotación de secretos periódicamente o de inmediato si sospechas que el 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

Navigate to Webhook Details

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

Select Your Endpoint

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

Open Event Settings

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

Gestionando suscripciones de eventos

1

View Available Events

La interfaz muestra todos los eventos de webhook disponibles organizados en una estructura jerárquica. Los eventos se agrupan por categoría (p. ej., dispute, payment, subscription).
2

Search and Filter

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

Select Events

Marca las casillas junto a los eventos que deseas recibir. Puedes:
  • Seleccionar subeventos individuales (p. ej., dispute.accepted, dispute.challenged)
  • Seleccionar eventos principales para recibir todos los subeventos relacionados
  • Combinar eventos específicos según tus necesidades
4

Review Event Details

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

Save Configuration

Haz clic en Save para aplicar tus cambios, o en Cancel para descartar las modificaciones.
Si desmarcas 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 forma asincrónica reconociendo la recepción inmediatamente con un código de estado 200 y luego manejando 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 evitar 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 comprobaciones de idempotencia. Debido a los reintentos, puedes recibir el mismo evento varias 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, sin importar 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 del payload 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 payloads sin verificación
Proporciona tu secreto de webhook mediante 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 sin modificar payload exacta, separados por puntos (.).
  2. Calcula el HMAC SHA256 de esa cadena usando 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 Standard Webhooks. Puedes usar sus bibliotecas para verificar firmas: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. Para los formatos de payload de eventos, consulta el Webhook Payload.

Respondiendo a Webhooks

  • Tu manejador de webhooks debe devolver un código de estado 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

Usa siempre URLs HTTPS para los endpoints de webhook. Los endpoints HTTP son vulnerables a ataques man-in-the-middle y exponen tus datos de webhook.
Devuelve un código de estado 200 inmediatamente al recibir el webhook. Procesa el evento de forma asincrónica para evitar tiempos de espera.
app.post('/webhook', async (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).json({ received: true });
  
  // Process asynchronously
  processWebhookAsync(req.body).catch(console.error);
});
Implementa la idempotencia utilizando el encabezado webhook-id para procesar de forma segura el mismo evento múltiples veces sin efectos secundarios.
Almacena tu secreto de webhook de forma segura usando 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
requerido
Identificador único para este evento de webhook. Úsalo para comprobaciones de idempotencia.
webhook-signature
string
requerido
Firma HMAC SHA256 para verificar la autenticidad del webhook.
webhook-timestamp
string
requerido
Marca de tiempo Unix (en segundos) cuando se envió el webhook.

Cuerpo de la solicitud

business_id
string
requerido
Identificador de negocio de Dodo Payments.
type
string
requerido
Tipo de evento que activó este webhook (por ejemplo, payment.succeeded, subscription.active).
timestamp
string
requerido
Marca de tiempo en formato ISO 8601 de cuándo ocurrió el evento.
data
object
requerido
Payload específico 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.
Endpoint Details

Accediendo a la interfaz de prueba

1

Navigate to Webhooks

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

Select Your Endpoint

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

Open Testing Tab

Haz clic en la pestaña Testing para acceder a la interfaz de pruebas de webhook.

Probando tu Webhook

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

Select Event Type

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

Review Schema and Example

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

Send Test Event

Haz clic en el botón Send Example para enviar un webhook de prueba a tu endpoint.
Importante: Los mensajes fallidos enviados a través de la interfaz de pruebas no se reintentarán. Esto es solo para pruebas.

Verificando tu prueba

1

Check Your Endpoint

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

Verify Signature

Asegúrate de que la verificación de firma funcione correctamente con el payload de prueba.
3

Test Response

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.active':
      await handleSubscriptionActive(data);
      break;
    // Add more event handlers...
  }
}
Prueba a fondo tu manejador de webhooks usando la interfaz de pruebas del panel antes de procesar eventos de producción. Esto ayuda a identificar y solucionar problemas anticipadamente.

Testing Webhooks with the CLI

The Dodo Payments CLI proporciona dos comandos para probar webhooks durante el desarrollo local, sin necesidad de salir de tu terminal.

Listen for Live Webhooks Locally

Reenvía eventos de webhook reales de tu cuenta en modo prueba a tu servidor de desarrollo local en tiempo real:
dodo wh listen
El CLI abre una conexión WebSocket a Dodo Payments y reenvía cada evento de webhook a tu endpoint local (p. ej., http://localhost:3000/webhook), preservando todos los encabezados incluidos los de firma para pruebas de verificación.
El listener solo funciona con claves API en modo prueba. Ejecuta dodo login y selecciona Test Mode antes de usar este comando.

Trigger Mock Webhook Events

Envía payloads de webhook simulados a cualquier endpoint sin crear transacciones reales:
dodo wh trigger
Esta herramienta interactiva te permite seleccionar entre los 22 tipos de eventos compatibles y envía payloads simulados realistas a tu endpoint. Se repite para que puedas probar múltiples eventos en una sesión.
Los payloads de webhook simulados de dodo wh trigger no están firmados. Usa unsafe_unwrap() en lugar de unwrap() en tu manejador durante las pruebas únicamente.

CLI Webhook Testing Docs

Consulta la documentación completa de pruebas de webhook del CLI

Advanced Settings

La pestaña Advanced Settings proporciona opciones de configuración adicionales para afinar el comportamiento de tu endpoint de webhook.

Rate Limiting (Throttling)

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

Access Rate Limit Settings

En la pestaña Advanced, localiza la sección “Rate Limit (throttling)”.
2

Configure Rate Limit

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

Set Limits

Configura el límite de velocidad que desees para controlar la frecuencia de entrega de webhooks y evitar sobrecargas en el sistema.
Usa el rate limiting cuando tu manejador de webhooks necesite tiempo para procesar eventos o cuando quieras agrupar varios eventos.

Custom Headers

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

Add Custom Header

En la sección “Custom Headers”, ingresa una Key y un Value para tu encabezado personalizado.
2

Add Multiple Headers

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

Save Configuration

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

Transformations

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

Enable Transformations

Activa el interruptor Enabled para habilitar la función de transformación.
2

Configure Transformation

Haz clic en Edit transformation para definir tus reglas de transformación.
Puedes usar JavaScript para transformar el payload del webhook y especificar una URL de destino diferente.
3

Test Transformation

Usa la interfaz de pruebas para verificar que tu transformación funciona correctamente antes de pasar a 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 especialmente útiles para:
  • Convertir entre diferentes formatos de datos
  • Filtrar eventos según criterios específicos
  • Agregar campos calculados al payload
  • Enrutar eventos a diferentes microservicios

Monitoring Webhook Logs

La pestaña Logs proporciona visibilidad completa del estado de entrega de tus webhooks, lo que te permite monitorear, depurar y gestionar eventos de webhook de forma efectiva.
Logs

Activity Monitoring

La pestaña Activity ofrece información en tiempo real sobre el rendimiento de entrega de tus webhooks con análisis visuales.
Activity

Email Alerts

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 para que puedas resolver problemas rápidamente y mantener tus integraciones en funcionamiento.
Webhook Alerting Settings showing email notifications configuration

Enable Email Alerts

1

Navigate to Alerting Settings

Ve al panel de Dodo Payments y navega a Dashboard → Webhooks → Alerting.
2

Enable Email Notifications

Activa Email notifications para empezar a recibir alertas sobre problemas de entrega de webhooks.
3

Configure Email Address

Ingresa la dirección de correo electrónico donde deseas recibir las 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.
Activa las alertas por correo para detectar problemas de entrega de webhooks temprano y mantener integraciones confiables. Serás notificado cuando las entregas fallen o tu endpoint deje de responder.

Deploy to Cloud Platforms

¿Listo para desplegar tu manejador de webhooks en producción? Ofrecemos guías específicas por 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 de entorno, verificación de firmas y pasos de despliegue específicos para ese proveedor.