Skip to main content
Imagen de portada del Webhook
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.

Key Features

Real-time Delivery

Receive instant notifications when events occur

Secure by Default

HMAC SHA256 signature verification included

Automatic Retries

Built-in retry logic with exponential backoff

Event Filtering

Subscribe only to events you need

Getting Started

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.

Integration Connectors

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.

How Connectors Work

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: 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.

Setting Up a Connector

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.

Configuring Subscribed Events

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 eventos individuales (por ejemplo, payment.succeeded, payment.failed)
  • 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.

Event Catalog

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.

Webhook Delivery

Timeouts

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.

Automatic Retries

Si falla la entrega de un webhook, Dodo Payments vuelve a intentarlo automáticamente con un exponential backoff para evitar sobrecargar tu sistema.
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.

Idempotency

Cada evento de webhook incluye un header webhook-id único. Usa este identificador para implementar idempotency y evitar el procesamiento duplicado.
Implementa siempre comprobaciones de idempotency. Debido a los retries, puedes recibir el mismo evento varias veces.

Event Ordering

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.

Securing Webhooks

Para garantizar la seguridad de tus webhooks, valida siempre los payloads y usa HTTPS.

Verifying Signatures

Cada webhook request incluye un header webhook-signature, una firma HMAC SHA256 del webhook payload y el timestamp, firmada con tu secret key. Todos los SDK oficiales incluyen helpers integrados para validar y analizar de forma segura los webhooks entrantes. Hay dos métodos disponibles:
  • unwrap(): verifica firmas usando tu webhook secret key
  • unsafe_unwrap(): analiza payloads sin verificación
Proporciona tu webhook secret mediante DODO_PAYMENTS_WEBHOOK_KEY al inicializar el cliente de Dodo Payments.

Manual verification (alternative)

Si no usas un SDK, puedes verificar las firmas siguiendo la especificación de Standard Webhooks:
  1. Construye el mensaje firmado concatenando webhook-id, webhook-timestamp y la cadena exacta serializada de payload, separados por puntos (.).
  2. Calcula el HMAC SHA256 de esa cadena usando tu webhook secret key del Dashboard.
  3. Compara la firma calculada con el header webhook-signature. Si coinciden, el webhook es auténtico.
Seguimos la especificación de Standard Webhooks. Puedes usar sus libraries para verificar firmas: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. Para consultar los formatos de los event payloads, visita Webhook Payload.

Responding to Webhooks

  • Tu webhook handler debe devolver un 2xx status code para confirmar la recepción del evento.
  • Cualquier otra respuesta se tratará como un fallo y el webhook volverá a intentarse.

Best Practices

Usa siempre URLs HTTPS para los webhook endpoints. Los endpoints HTTP son vulnerables a ataques man-in-the-middle y exponen tus datos de webhook.
Devuelve inmediatamente un código de estado 200 al recibir el webhook. Procesa el evento de forma asíncrona para evitar timeouts.
Implementa idempotency usando el header webhook-id para procesar de forma segura el mismo evento varias veces sin efectos secundarios.
Almacena tu webhook secret de forma segura usando variables de entorno o un secrets manager. Nunca hagas commit de secrets en el control de versiones.

Webhook Payload Structure

Comprender la estructura del webhook payload te ayuda a analizar y procesar los eventos correctamente.

Request Format

Headers

string
requerido
Identificador único de este evento de webhook. Úsalo para las comprobaciones de idempotency.
string
requerido
Firma HMAC SHA256 para verificar la autenticidad del webhook.
string
requerido
Timestamp de Unix (en segundos) en el que se envió el webhook.

Request Body

string
requerido
Identificador de tu empresa en Dodo Payments.
string
requerido
Tipo de evento que activó este webhook (por ejemplo, payment.succeeded, subscription.active).
string
requerido
Timestamp con formato ISO 8601 del momento en que ocurrió el evento.
object
requerido
Payload específico del evento que contiene información detallada sobre este.

Example Payload

Event Types

Consulta todos los tipos de webhook events disponibles

Event Payloads

Consulta los schemas detallados del payload de cada evento

Handle Payment Failures

Reacciona a payment.failed y recupera pagos rechazados

Testing Webhooks

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.

Send an Example Event

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.

Implementation Example

Este es un ejemplo completo de Express.js que muestra la verificación y gestión de webhooks:
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.

Testing Webhooks with the CLI

La Dodo Payments CLI proporciona dos comandos para probar webhooks durante el desarrollo local sin necesidad de salir del terminal.

Listen for Live Webhooks Locally

Reenvía eventos de webhook reales desde tu cuenta en test mode a tu servidor de desarrollo local en tiempo real:
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.

Trigger Mock Webhook Events

Envía webhook payloads simulados a cualquier endpoint sin crear transacciones reales:
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

Advanced Settings

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

Rate Limiting (Throttling)

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

Open Advanced Tab

Desde la página de detalles de tu endpoint, haz clic en la pestaña Advanced.
2

Configure Rate Limit

En la sección “Rate Limit (throttling)”, haz clic en Edit para modificar la configuración del rate limit.
De forma predeterminada, los webhooks no tienen ningún rate limit aplicado, lo que significa que los eventos se entregan tan pronto como ocurren.
3

Set Your Limit

Configura el rate limit que desees para controlar la frecuencia de entrega de webhooks y evitar la sobrecarga del sistema.
Usa rate limiting cuando tu webhook handler necesite tiempo para procesar eventos o cuando quieras agrupar varios eventos.

Custom Headers

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.

Transformations

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:
  • Convertir entre distintos formatos de datos
  • Filtrar eventos según criterios específicos
  • Añadir campos calculados al payload
  • Dirigir eventos a distintos microservices

Monitoring Webhook Logs

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.

Activity Monitoring

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.

Replaying and Recovering Messages

La forma de volver a enviar un mensaje depende de cuántos necesites reenviar:
  • Un mensaje: ábrelo desde la pestaña Logs y usa la acción Replay en el intento. No es necesario abrir el endpoint.
  • Un intervalo de mensajes: abre el endpoint, ya que los modos masivos actúan sobre un solo endpoint cada vez.

Replaying in Bulk

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:
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.

Email Alerts

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.

Deploy to Cloud Platforms

¿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.

Create Webhook

Referencia de API para crear y configurar webhook endpoints mediante programación

List Webhooks

Referencia de API para recuperar y gestionar tus webhook endpoints
Última modificación el 8 de agosto de 2026