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.

Direcciones IP de origen

La verificación de firmas es la forma compatible de autenticar un webhook. Demuestra que la solicitud se firmó con tu secreto de webhook, algo que una comprobación a nivel de red no puede hacer. Las entregas de webhooks se envían desde un conjunto de direcciones IP de origen que pertenecen a nuestra infraestructura de entrega. Este conjunto cambia ocasionalmente, así que trata las direcciones como un detalle operativo y no como una propiedad fija de la integración.
No uses una lista de permitidos de IP de origen como mecanismo de autenticación. Una lista de permitidos solo muestra de dónde provino una solicitud, no que sea auténtica o no haya sido modificada; verifica el encabezado webhook-signature en cada solicitud, tal como se describe en Verificación de firmas.
Si tu infraestructura se encuentra detrás de un firewall que requiere una lista de permitidos explícita, ten en cuenta lo siguiente:
  • No codifiques las direcciones de forma permanente. Los rangos se agregan y retiran con el tiempo, y una regla obsoleta bloquea las entregas silenciosamente.
  • Solicita los rangos actuales a support@dodopayments.com antes de restringir un firewall, para trabajar con una lista actualizada.
  • Presta atención a los avisos de cambios. Cuando cambian las direcciones de entrega, notificamos por correo electrónico a los merchants afectados; aplica esas actualizaciones antes de la fecha indicada para evitar que se pierdan entregas.
  • Mantén habilitada la verificación de firmas independientemente de las reglas de red que agregues.
En las plataformas serverless y de hosting administrado, el filtrado de IP entrante suele no estar disponible o ser poco práctico de mantener. La verificación de firmas es el control adecuado en esos entornos y no se requiere ninguna lista de permitidos.
Una entrega bloqueada se trata como cualquier otro error y se reintenta según el calendario descrito en Reintentos automáticos. Si las reglas del firewall provocaron el error en las entregas, puedes volver a enviarlas una vez corregidas las reglas; consulta Reproducción y recuperación de mensajes.

Responder a los webhooks

  • Tu controlador de webhook debe devolver un 2xx status code para confirmar la recepción del evento.
  • Cualquier otra respuesta se tratará como un error y el webhook se reintentará.

Prácticas recomendadas

Usa siempre URL HTTPS para los endpoints de webhook. Los endpoints HTTP son vulnerables a ataques de intermediario y exponen los datos de tus webhooks.
Devuelve inmediatamente un código de estado 200 al recibir el webhook. Procesa el evento de forma asíncrona para evitar tiempos de espera agotados.
Implementa la idempotencia mediante el encabezado webhook-id para procesar de forma segura el mismo evento varias veces sin efectos secundarios.
Almacena tu secreto de webhook de forma segura mediante variables de entorno o un gestor de secretos. Nunca confirmes secretos en el control de versiones.

Estructura de la carga útil del webhook

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

Formato de la solicitud

Encabezados

string
requerido
Identificador único de este evento de webhook. Úsalo para las comprobaciones de idempotencia.
string
requerido
Firma HMAC SHA256 para verificar la autenticidad del webhook.
string
requerido
Marca de tiempo Unix, en segundos, correspondiente al momento en que se envió el webhook.

Cuerpo de la solicitud

string
requerido
Identificador de tu negocio en Dodo Payments.
string
requerido
Tipo de evento que activó este webhook (por ejemplo, payment.succeeded, subscription.active).
string
requerido
Marca de tiempo con formato ISO 8601 del momento en que ocurrió el evento.
object
requerido
Carga útil específica del evento que contiene información detallada sobre este.

Ejemplo de carga útil

Event Types

Explorar todos los tipos de eventos de webhook disponibles

Event Payloads

Ver los esquemas detallados de carga útil de cada evento

Handle Payment Failures

Reaccionar a payment.failed y recuperar pagos rechazados

Probar 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 ponerlo en 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 el 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 prueba de webhooks.

Enviar un evento de ejemplo

La pestaña Testing envía una carga útil 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. La carga útil de ejemplo se entrega a la URL de tu endpoint exactamente como un evento real y se firma de la misma manera.
Los mensajes fallidos enviados desde la pestaña Testing no se reintentan. Úsala para verificar tu receptor, no para probar el calendario de reintentos.
3

Check Your Endpoint

La pestaña registra cuándo se envió Last example sent. Confirma que el evento llegó, que la verificación de firmas se realizó correctamente y que devolviste un código de estado 2xx.

Ejemplo de implementación

Esta es una implementación completa con Express.js que muestra la verificación y el manejo de webhooks:
Prueba exhaustivamente tu controlador de webhook mediante la interfaz de pruebas del dashboard antes de procesar eventos de producción. Esto ayuda a identificar y corregir problemas a tiempo.

Probar webhooks con la CLI

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

Escuchar webhooks activos localmente

Reenvía eventos de webhook reales desde tu cuenta en modo de prueba 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 encabezados, incluidos los de firma, para probar la verificación.
El listener solo funciona con claves API de test mode. Ejecuta dodo login y selecciona Test Mode antes de usar este comando.

Activar eventos de webhook simulados

Envía cargas útiles de webhook simuladas a cualquier endpoint sin crear transacciones reales:
Esta herramienta interactiva te permite elegir un tipo de evento y envía una carga útil simulada realista a tu endpoint. Se repite para que puedas probar varios eventos en una misma sesión. El comando de activación incluye los 47 tipos de eventos que entrega Dodo Payments, incluidas las familias de suscripciones, pagos, reembolsos, disputas, claves de licencia, pagos a merchants, créditos, checkouts abandonados, gestión de cobros y concesiones de derechos; consulta Eventos de webhook compatibles para ver la lista exacta.
Las cargas útiles de webhook simuladas de dodo wh trigger no están firmadas. Usa unsafe_unwrap() en lugar de unwrap() en tu controlador de webhook únicamente durante las pruebas.

CLI Webhook Testing Docs

Consulta la documentación completa de pruebas de webhooks de la CLI

Configuración avanzada

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

Limitación de velocidad (throttling)

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

Open Advanced Tab

En 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 límite de velocidad.
De forma predeterminada, los webhooks no tienen ningún límite de velocidad aplicado, lo que significa que los eventos se entregan en cuanto ocurren.
3

Set Your Limit

Configura el límite de velocidad que prefieras para controlar la frecuencia de entrega de webhooks y evitar la sobrecarga del sistema.
Usa la limitación de velocidad cuando tu controlador de webhook necesite tiempo para procesar eventos o cuando quieras agrupar varios eventos.

Encabezados personalizados

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

Add Headers

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

Add Multiple Headers

Haz clic en el botón + para agregar los encabezados personalizados adicionales que necesites.
Tus encabezados personalizados se incluyen en todas las solicitudes de webhook a este endpoint.

Transformaciones

Las transformaciones te permiten modificar la carga útil de un webhook y, opcionalmente, redirigirlo a una URL diferente. Esta potente función te permite:
  • Modificar la estructura de la carga útil antes de procesarla
  • Enrutar webhooks a diferentes endpoints según su contenido
  • Agregar o eliminar campos de la carga útil
  • 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 las reglas de transformación con JavaScript.
3

Test Transformation

Usa la interfaz de prueba de transformaciones para verificar que tu transformación funciona correctamente antes de ponerla en producción.
Las transformaciones pueden afectar al rendimiento de la entrega de webhooks. Pruébalas exhaustivamente y mantén la lógica de transformación sencilla y eficiente.
Las transformaciones son especialmente útiles para:
  • Convertir entre distintos formatos de datos
  • Filtrar eventos según criterios específicos
  • Agregar campos calculados a la carga útil
  • Enrutar eventos a diferentes microservicios

Supervisar los registros de webhooks

La pestaña Logs proporciona visibilidad completa del estado de entrega de tus webhooks, lo que te permite supervisar, depurar y gestionar eventos de webhook de forma eficaz.
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, con 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 la página de detalles del mensaje, que muestra:
  • La carga útil completa del webhook
  • Cada intento de entrega con el código de respuesta y la duración
  • La marca de tiempo de cada intento
  • Los mensajes de error del endpoint
Cada intento incluye una acción Replay, para que puedas volver a enviar ese mensaje sin salir de la página.

Supervisión de la actividad

Ve a Developer → Webhooks y abre la pestaña Activity para consultar el rendimiento de entrega en 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 abrir cualquiera de ellos.

Reproducción y recuperación de mensajes

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

Reproducción masiva

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 elige uno de los tres modos anteriores.
2

Set the Range

Completa el intervalo que solicite el 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, estado y número de mensajes reenviados.

Alertas por correo electrónico

Recibe una notificación por correo electrónico cuando fallen las entregas de webhooks a un endpoint, para poder resolver los problemas antes de que se conviertan en una acumulación de mensajes.
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.
Habilita las alertas por correo electrónico para detectar pronto los problemas de entrega de webhooks y mantener integraciones confiables.

Implementar en plataformas cloud

¿Listo para implementar tu controlador de webhook en producción? Proporcionamos guías específicas para cada plataforma que te ayudan a implementar webhooks en proveedores cloud populares, siguiendo las prácticas recomendadas de cada plataforma.

Vercel

Implementar webhooks en Vercel con funciones serverless

Cloudflare Workers

Ejecutar webhooks en la red perimetral de Cloudflare

Supabase Edge Functions

Integrar webhooks con Supabase

Netlify Functions

Implementar webhooks como funciones serverless de Netlify
Cada guía de plataforma incluye la configuración del entorno, la verificación de firmas y los pasos de implementación específicos de ese proveedor.

Referencia de API relacionada

Create Webhook

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

List Webhooks

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