Receive real-time notifications when events occur in Dodo Payments. Automate workflows and keep your systems synchronized with instant event delivery.
Webhooks provide real-time notifications when specific events occur in your Dodo Payments account. Use webhooks to automate workflows, update your database, send notifications, and keep your systems synchronized.
Our webhook implementation follows the Standard Webhooks specification, ensuring compatibility with industry best practices and existing webhook libraries.
El portal de webhooks de Dodo Payments se ha reconstruido con una experiencia de dashboard nativa. Tus endpoints existentes, signing secrets, verificación de firmas, nombres de eventos y payloads de webhook no han cambiado. No es necesario realizar ningún trabajo de integración.
Dónde se encuentra cada cosa.
En Developer → Webhooks: las pestañas Endpoints, Event catalog, Logs, Activity y Settings.
En un endpoint individual: la pestaña Overview, que contiene las estadísticas de entrega, el signing secret y el Replay history, además de las pestañas Testing y Advanced y las acciones de replay masivo.
En un mensaje: se abre desde la pestaña Logs, donde cada intento de entrega se puede reproducir individualmente sin abrir el endpoint.
1
Access Webhook Settings
Ve al Dashboard de Dodo Payments y dirígete a Developer → Webhooks.
2
Create Webhook Endpoint
Haz clic en Add endpoint para abrir el panel lateral de creación del endpoint.
3
Enter Endpoint URL or Choose Integration
Introduce la URL donde quieres recibir los eventos de webhook o selecciona un integration connector para dirigir los eventos a un servicio de terceros (Slack, Discord, Zapier, Resend, etc.).
4
Select Events to Receive
Elige los eventos específicos que tu endpoint debe escuchar. Los eventos están organizados en un árbol searchable agrupado por recurso. Puedes seleccionar eventos individuales o un recurso principal para recibir todos los eventos relacionados.
Solo los eventos seleccionados activarán webhooks en tu endpoint, lo que te ayuda a evitar tráfico y procesamiento innecesarios.
5
Create Endpoint
Haz clic en Create endpoint para guardar tu configuración.
6
Get Secret Key
Tu webhook signing secret se muestra en la pestaña Overview del endpoint. Lo usarás para verificar la autenticidad de los webhooks recibidos.
Mantén segura tu webhook secret key y nunca la expongas en código del lado del cliente ni en repositorios públicos.
7
Rotate Secret (Optional)
Si es necesario, puedes rotar tu webhook secret para mejorar la seguridad. Haz clic en Rotate secret, junto al secret en la pestaña Overview.
Al rotar el secret, este caducará y se reemplazará por uno nuevo. El secret anterior solo será válido durante las siguientes 24 horas. Después, la verificación con el secret anterior fallará.
Usa la rotación del secret periódicamente o de inmediato si sospechas que tu secret actual se ha visto comprometido.
En lugar de crear tu propio receptor de webhook, puedes dirigir los eventos de webhook directamente a servicios de terceros mediante integration connectors. Esto elimina la necesidad de escribir y mantener handlers de webhook personalizados para plataformas populares.
Un connector aplica una transformación que convierte el evento de Dodo Payments al formato que espera el destino. Los detalles que debes proporcionar dependen del destino:
Connector type
What you provide
Destinations
Incoming webhook URL
Una URL de webhook que creas en el dashboard del propio proveedor. No requiere API key.
El selector de connectors del dashboard muestra el conjunto completo disponible actualmente para tu empresa, así que considera la tabla anterior como los destinos con instrucciones de configuración paso a paso, no como una lista exhaustiva. Consulta External Integrations para saber qué puede hacer cada destino una vez que recibe los eventos.
Selecciona un connector al crear o editar un endpoint y el panel lateral mostrará instrucciones de configuración específicas para ese destino; por ejemplo, cómo crear una incoming webhook URL en Slack o dónde encontrar tu Resend API key. Antes de guardar, ejecuta la prueba de transformación del connector para confirmar que el evento se convierte correctamente para el destino.
Usa un connector para llegar a un destino compatible sin escribir código. Si necesitas lógica personalizada, usa un endpoint estándar con una transformation en su lugar.
Puedes configurar qué eventos específicos debe recibir cada webhook endpoint.
1
Navigate to Webhook Endpoints
Ve a tu Dashboard de Dodo Payments y dirígete a Developer → Webhooks.
2
Select Your Endpoint
Haz clic en el webhook endpoint que quieres configurar.
3
Open Event Configuration
Haz clic en Edit para abrir el panel lateral de configuración del endpoint.
4
Browse Event Types
El selector de tipos de evento muestra todos los webhook events disponibles organizados en un árbol searchable y agrupados por recurso (por ejemplo, payment, subscription, dispute). Usa la barra de búsqueda para encontrar rápidamente eventos específicos por nombre o palabra clave.
5
Select Events
Marca las casillas junto a los eventos que quieres recibir. Puedes:
Seleccionar un recurso principal para recibir todos los eventos relacionados
Combinar eventos específicos según tus necesidades
6
Save Configuration
Haz clic en Save para aplicar los cambios o en Cancel para descartar las modificaciones.
Si anulas la selección de todos los eventos, tu webhook endpoint no recibirá ninguna notificación. Asegúrate de seleccionar al menos los eventos que tu aplicación necesita para funcionar correctamente.
Ve a Developer → Webhooks y abre la pestaña Event catalog. En ella se muestra cada tipo de evento que Dodo Payments puede enviar, para que puedas consultar las opciones disponibles antes de suscribir un endpoint. Selecciona un evento para ver su schema y un payload de ejemplo; esta es la forma más rápida de comprobar el formato de un campo que planeas leer.
Webhook Events Guide
Consulta los mismos eventos como documentación de referencia, agrupados por recurso.
Los webhooks tienen una ventana de timeout de 15 segundos tanto para las operaciones de conexión como de lectura. Asegúrate de que tu endpoint responda rápidamente para evitar timeouts.
Procesa los webhooks de forma asíncrona confirmando la recepción de inmediato con un código de estado 200 y realizando el procesamiento real en segundo plano.
Si falla la entrega de un webhook, Dodo Payments vuelve a intentarlo automáticamente con un exponential backoff para evitar sobrecargar tu sistema.
Attempt
Delay
Description
1
Inmediatamente
El primer retry se realiza de inmediato
2
5 segundos
El segundo intento se realiza tras una breve espera
3
5 minutos
El tercer intento aplica un backoff mayor
4
30 minutos
El cuarto intento continúa el backoff
5
2 horas
El quinto intento aplica una espera extendida
6
5 horas
El sexto intento aplica una espera más larga
7
10 horas
El séptimo intento aplica la espera máxima
8
10 horas
Intento final: el webhook se marca como fallido si no tiene éxito
Máximo de 8 retry attempts 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.
Usa el dashboard de Dodo Payments para reintentar manualmente mensajes individuales o recuperar en bloque todos los mensajes fallidos en cualquier momento.
Los eventos de webhook pueden llegar desordenados debido a retries o a las condiciones de la red. Diseña tu sistema para gestionar los eventos en cualquier secuencia.
Recibirás el último payload en el momento de la entrega, independientemente de cuándo se emitió originalmente el evento de webhook.
Tipo de recurso. Puede ser uno de los siguientes: Payment, Subscription, Refund, Dispute, LicenseKey, CreditLedgerEntry, CreditBalanceLow, AbandonedCheckout, DunningAttempt, EntitlementGrant o Payout.
Los campos adicionales varían según el tipo de evento. Consulta la documentación específica del evento para ver los schemas completos.
Puedes probar tu integración de webhook directamente desde el dashboard de Dodo Payments para asegurarte de que tu endpoint funciona correctamente antes de pasar a producción.
1
Navigate to Webhooks
Ve a tu Dashboard de Dodo Payments y dirígete a Developer → Webhooks.
2
Select Your Endpoint
Haz clic en tu webhook endpoint 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 prueba de webhooks.
La pestaña Testing envía un payload de ejemplo a este endpoint para que puedas verificar tu receptor.
1
Select Event Type
Usa Select an event type para elegir el evento que quieres probar, por ejemplo payment.succeeded o payment.failed.
2
Send Example
Haz clic en Send example. El payload de ejemplo se entrega a la URL de tu endpoint exactamente como un evento real y se firma de la misma forma.
Los mensajes fallidos enviados desde la pestaña Testing no se reintentan. Usa esta función para verificar tu receptor, no para probar el retry schedule.
3
Check Your Endpoint
La pestaña registra cuándo se envió el Last example sent. Confirma que el evento llegó, que la verificación de la firma fue correcta y que devolviste un código de estado 2xx.
Prueba exhaustivamente tu webhook handler mediante la interfaz de pruebas del dashboard antes de procesar eventos de producción. Esto ayuda a identificar y corregir problemas con antelación.
Reenvía eventos de webhook reales desde tu cuenta en test mode a tu servidor de desarrollo local en tiempo real:
dodo wh listen
La CLI abre una conexión WebSocket con Dodo Payments y reenvía cada evento de webhook a tu endpoint local (por ejemplo, http://localhost:3000/webhook), conservando todos los headers, incluidos los de firma, para probar la verificación.
El listener solo funciona con API keys de test mode. Ejecuta dodo login y selecciona Test Mode antes de usar este comando.
Envía webhook payloads simulados a cualquier endpoint sin crear transacciones reales:
dodo wh trigger
Esta herramienta interactiva te permite elegir un tipo de evento y envía un payload simulado realista a tu endpoint. Funciona en bucle para que puedas probar varios eventos en una misma sesión.El comando trigger incluye los 46 tipos de eventos que Dodo Payments entrega, incluidas las familias de subscription, payment, refund, dispute, license key, payout, credit, abandoned checkout, dunning y entitlement grant. Consulta Supported Webhook Events para ver la lista exacta.
Los webhook payloads simulados de dodo wh trigger no están firmados. Usa unsafe_unwrap() en lugar de unwrap() en tu webhook handler únicamente durante las pruebas.
CLI Webhook Testing Docs
Consulta la documentación completa de pruebas de webhooks de la CLI
Añade HTTP headers personalizados a todas las webhook requests enviadas a tu endpoint. Esto resulta útil para autenticación, routing o para añadir metadata.
1
Add Headers
En la sección “Custom Headers”, introduce una Key y un Value para cada header personalizado.
2
Add Multiple Headers
Haz clic en el botón + para añadir los headers personalizados adicionales que necesites.
Tus headers personalizados se incluyen en todas las webhook requests dirigidas a este endpoint.
Las transformations permiten modificar el payload de un webhook y, opcionalmente, redirigirlo a una URL diferente. Esta potente función permite:
Modificar la estructura del payload antes de procesarlo
Dirigir los webhooks a distintos endpoints según su contenido
Añadir o eliminar campos del payload
Transformar formatos de datos
1
Enable Transformations
Activa el interruptor Enabled para habilitar la función de transformation.
2
Configure Transformation
Haz clic en Edit transformation para definir tus reglas de transformación usando JavaScript.
3
Test Transformation
Usa la interfaz de prueba de transformations para verificar que funcionan correctamente antes de pasar a producción.
Las transformations pueden afectar al rendimiento de entrega de los webhooks. Haz pruebas exhaustivas y mantén la lógica de transformación sencilla y eficiente.
Las transformations son especialmente útiles para:
La pestaña Logs proporciona visibilidad completa sobre el estado de entrega de tus webhooks, lo que te permite monitorizar, depurar y gestionar los eventos de webhook eficazmente.
1
Navigate to Logs Tab
Ve a Developer → Webhooks y abre la pestaña Logs.
2
Browse Delivery History
Consulta una tabla con todos los intentos de entrega de webhooks y columnas para Event type, Message ID, Event ID, Sent at, Attempted at, Response code y Duration.
3
Search and Filter
Usa la barra de búsqueda para encontrar mensajes específicos por ID o tipo de evento. Filtra por estado (Succeeded, Failed, Pending, etc.) para centrarte en los eventos que necesitas investigar.
4
View Message Details
Haz clic en cualquier mensaje para abrir su página de detalles, que muestra:
El webhook payload completo
Cada intento de entrega con su response code y duración
El timestamp de cada intento
Cualquier mensaje de error de tu endpoint
Cada intento incluye una acción Replay, para que puedas volver a enviar ese mensaje sin salir de la página.
Ve a Developer → Webhooks y abre la pestaña Activity para consultar el rendimiento de entrega de todos tus endpoints.Delivery activity representa los intentos a lo largo del tiempo, agrupados como Attempts per 5 minutes, Attempts per hour o Attempts per day, según el intervalo. Cada barra se divide por resultado y, al pasar el cursor sobre un segmento, se muestran el estado, el número de intentos y su proporción del total. En un endpoint, Delivery stats (last 24h) de la pestaña Overview resume la misma información del último día.
La columna Error rate (24h) de la pestaña Endpoints te indica de un vistazo qué endpoints requieren atención, antes de abrirlos.
Abre el endpoint desde Developer → Webhooks. Hay tres modos disponibles y cada uno actúa únicamente sobre ese endpoint. El intervalo que configures depende del modo:
Mode
What it does
What you set
Recover failed messages
Reproduce cada mensaje dirigido a este endpoint que haya fallado.
Un punto de inicio: 8 hours ago, Yesterday, 3 days ago, Last week o 2 weeks ago
Replay missing messages
Reproduce los mensajes que nunca se enviaron a este endpoint, por ejemplo, después de suscribirlo a un nuevo tipo de evento.
Los mismos puntos de inicio
Bulk replay messages
Reproduce los mensajes que coincidan con los filtros elegidos, incluidos los que ya se entregaron correctamente.
Límites Since y Until, con un valor predeterminado de las últimas dos semanas, además de tipos de evento, canal o tag opcionales
1
Open More Actions
En el endpoint, abre More actions y selecciona uno de los tres modos anteriores.
2
Set the Range
Introduce el intervalo que solicita ese modo, tal como se indica en la tabla.
3
Start the Run
Haz clic en Recover o Replay, según el modo que hayas elegido.
Cada ejecución aparece en Replay history, en la pestaña Overview del endpoint, junto con su modo, intervalo de tiempo, estado y número de mensajes reenviados.
Recibe una notificación por email cuando fallen las entregas de webhooks a un endpoint, para poder resolver los problemas antes de que se conviertan en una cola de mensajes pendientes.
1
Navigate to Settings Tab
Ve a Developer → Webhooks y abre la pestaña Settings.
2
Find Email Alerting
Busca la tarjeta Email alerting.
3
Configure Email Addresses
Introduce las direcciones que deben recibir las alertas. Separa varias direcciones con comas y deja el campo vacío para desactivar las alertas.
4
Save
Haz clic en Save para aplicar los cambios.
Activa las alertas por email para detectar pronto los problemas de entrega de webhooks y mantener integraciones fiables.
¿Listo para desplegar tu webhook handler en producción? Proporcionamos guías específicas por plataforma para ayudarte a desplegar webhooks en proveedores cloud populares siguiendo las mejores prácticas de cada plataforma.
Vercel
Despliega webhooks en Vercel con serverless functions
Cloudflare Workers
Ejecuta webhooks en la edge network de Cloudflare
Supabase Edge Functions
Integra webhooks con Supabase
Netlify Functions
Despliega webhooks como Netlify serverless functions
Cada guía de plataforma incluye la configuración del entorno, la verificación de firmas y los pasos de despliegue específicos de ese proveedor.