Recibe notificaciones en tiempo real cuando ocurren eventos en Dodo Payments. Automatiza flujos de trabajo y mantiene tus sistemas sincronizados con la entrega instantánea de eventos.
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.
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.
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.
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.
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 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.
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.
Si falla la entrega de un webhook, Dodo Payments reintenta automáticamente con retroceso exponencial para evitar abrumar tu sistema.
Intento
Retraso
Descripción
1
Inmediatamente
El primer reintento ocurre de inmediato
2
5 segundos
Segundo intento después de un breve retraso
3
5 minutos
Tercer intento con un retroceso aumentado
4
30 minutos
Cuarto intento continuando el retroceso
5
2 horas
Quinto intento con un retraso extendido
6
5 horas
Sexto intento con un retraso más largo
7
10 horas
Séptimo intento con el retraso máximo
8
10 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.
Cada evento de webhook incluye un encabezado único webhook-id. Usa este identificador para implementar idempotencia y prevenir el procesamiento duplicado.
Copiar
// Example: Storing webhook IDs to prevent duplicate processingconst 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.
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.
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.
Siempre utiliza URLs HTTPS para los endpoints de webhook. Los endpoints HTTP son vulnerables a ataques de intermediarios y exponen tus datos de webhook.
Responder inmediatamente
Devuelve un código de estado 200 inmediatamente al recibir el webhook. Procesa el evento de manera asíncrona para evitar timeouts.
Implementa idempotencia utilizando el encabezado webhook-id para procesar de manera segura el mismo evento múltiples veces sin efectos secundarios.
Asegura tu secreto de webhook
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.
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.
Aquí hay una implementación completa de Express.js que muestra la verificación y el manejo de webhooks:
Copiar
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.
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.
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:
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.
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.
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.
¿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.