Skip to main content
Imagen de portada del Webhook
Los webhooks envían notificaciones en tiempo real cuando ocurren eventos en tu cuenta de Dodo Payments. Úsalos para automatizar flujos de trabajo, actualizar tu base de datos, enviar notificaciones y mantener tus sistemas sincronizados.
Los webhooks de Dodo Payments siguen la especificación de Standard Webhooks para la verificación de firmas y la estructura del payload.

Key Features

Los webhooks ofrecen entrega en tiempo real con seguridad integrada, reintentos automáticos y filtrado de eventos. Todos los SDK oficiales incluyen helpers de verificación de firmas, y el dashboard ofrece herramientas de prueba, supervisión y repetición.

Getting Started

1

Go to Developer → Webhooks

En el Dashboard de Dodo Payments, ve a Developer → Webhooks.
2

Click Add Endpoint

Haz clic en Add endpoint para crear un nuevo receptor de webhooks.
3

Enter Your Endpoint URL

Proporciona la URL HTTPS donde Dodo Payments enviará los eventos de webhook, o selecciona un conector de integración (Slack, Discord, Zapier, Resend, etc.) para dirigir los eventos a un servicio de terceros sin escribir código.
4

Select Events

Elige qué eventos recibir. Los eventos están organizados por recurso (pago, suscripción, disputa, etc.). Puedes seleccionar eventos individuales o un recurso completo para recibir todos los eventos relacionados.
5

Save

Haz clic en Create endpoint. Tu secreto de firma del webhook aparece en la pestaña Overview del endpoint.
Mantén seguro tu secreto del webhook. Nunca lo expongas en código del lado del cliente ni en el control de versiones.
Para rotar tu secreto del webhook, abre el endpoint y haz clic en Rotate secret, junto al secreto, en la pestaña Overview. El secreto anterior sigue siendo válido durante 24 horas después de la rotación.

Conectores de integración

Dirige los eventos de webhook directamente a servicios de terceros mediante conectores de integración, eliminando la necesidad de crear y mantener handlers de webhook personalizados.

Cómo funcionan los conectores

Un conector transforma los eventos de Dodo Payments al formato que espera el destino. Los datos que debes proporcionar dependen del destino: El dashboard muestra todos los conectores disponibles para tu empresa. Consulta External Integrations para saber qué puede hacer cada destino con los eventos.

Configurar un conector

Al crear o editar un endpoint, selecciona un conector y el panel lateral mostrará las instrucciones de configuración para ese destino. Prueba la transformación antes de guardar para confirmar que los eventos se convierten correctamente.
Usa un conector para llegar a un destino compatible sin escribir código. Si necesitas lógica personalizada, utiliza un endpoint estándar con una transformación.

Configurar eventos suscritos

Configura qué eventos recibe cada endpoint de webhook.
1

Navigate to Webhook Endpoints

Ve a Developer → Webhooks y haz clic en tu endpoint.
2

Open Event Configuration

Haz clic en Edit para abrir el panel lateral de configuración del endpoint.
3

Select Events

El selector de tipos de evento muestra todos los eventos de webhook disponibles en un árbol que se puede buscar, agrupados por recurso (por ejemplo, payment, subscription, dispute). Marca las casillas junto a los eventos que quieres recibir. Puedes seleccionar eventos individuales, un recurso completo o combinarlos.
4

Save Configuration

Haz clic en Save para aplicar los cambios.
Si anulas la selección de todos los eventos, tu endpoint de webhook recibe todos los tipos de evento. Selecciona solo los eventos que necesita tu aplicación.

Catálogo de eventos

Ve a Developer → Webhooks y abre la pestaña Event catalog para ver todos los tipos de evento que puede enviar Dodo Payments. Selecciona un evento para ver su esquema y payload de ejemplo.

Webhook Events Guide

Explora los eventos como documentación de referencia, agrupados por recurso.

Entrega de webhooks

Timeouts

Los webhooks tienen un tiempo de espera de 30 segundos tanto para las operaciones de conexión como de lectura. Procesa los webhooks de forma asíncrona devolviendo inmediatamente un código de estado 200 y gestionando después el evento en segundo plano.

Reintentos automáticos

Las entregas fallidas se reintentan con un retroceso exponencial, hasta un total de 8 intentos: Usa el panel para volver a reproducir manualmente los mensajes fallidos o recuperar en bloque los mensajes de un intervalo de tiempo específico.

Idempotencia

Cada webhook incluye un encabezado webhook-id único. Almacena este ID para detectar y omitir eventos duplicados, ya que los reintentos pueden entregar el mismo evento varias veces.
Implementa siempre comprobaciones de idempotencia. Debido a los reintentos, puedes recibir el mismo evento varias veces.

Orden de los eventos

Los eventos pueden llegar desordenados debido a los reintentos o a las condiciones de la red. Cada webhook incluye un campo timestamp; úsalo para ordenar los eventos si tu aplicación lo requiere. Siempre recibes el estado más reciente del payload en el momento de la entrega.

Protección de los webhooks

Valida siempre los payloads de los webhooks y usa HTTPS.

Verificación de firmas

Cada webhook incluye un encabezado webhook-signature: una firma HMAC SHA256 del payload y la marca de tiempo, firmada con tu clave secreta.

Verificación mediante SDK (recomendado)

Todos los SDK oficiales incluyen helpers integrados. Configura DODO_PAYMENTS_WEBHOOK_KEY al inicializar el cliente y, después, llama a unwrap() para verificar y analizar el payload. Hay dos métodos disponibles:
  • unwrap — Verifica la firma con tu clave secreta del webhook y después analiza el payload.
  • unsafe_unwrap — Analiza el payload sin verificarlo. Úsalo solo para realizar pruebas.
Los nombres de los métodos siguen las convenciones de cada lenguaje: unwrap / unsafeUnwrap en TypeScript, unwrap / unsafe_unwrap en Python y Unwrap / UnsafeUnwrap en Go.
Proporciona tu secreto del webhook mediante DODO_PAYMENTS_WEBHOOK_KEY al inicializar el cliente de Dodo Payments.

Verificación manual (alternativa)

Si no usas un SDK, verifica la firma por tu cuenta:
  1. Construye el contenido firmado uniendo webhook-id, webhook-timestamp y el cuerpo sin procesar de la solicitud con puntos: {id}.{timestamp}.{body}. Usa el cuerpo sin procesar exactamente como se recibió, antes de analizar cualquier JSON.
  2. Toma tu secreto del webhook. Si comienza por whsec_, elimina ese prefijo y, después, decodifica en base64 el resto para obtener la clave de firma.
  3. Calcula el HMAC-SHA256 del contenido firmado con la clave de firma y codifica el resultado en base64.
  4. El encabezado webhook-signature contiene una o más firmas separadas por espacios, cada una con el formato v1,<base64-signature>. La solicitud es válida si alguna firma v1 coincide con la tuya. Compara mediante una función de tiempo constante.
  5. Rechaza la solicitud si webhook-timestamp difiere demasiado de la hora actual para evitar ataques de repetición. Las bibliotecas de Standard Webhooks permiten 5 minutos.
Consulta las bibliotecas de Standard Webhooks para ver implementaciones de referencia. Para consultar los formatos de payload de los eventos, visita Payload del webhook.

Direcciones IP de origen

La verificación de firmas es el método de autenticación compatible. Demuestra que la solicitud se firmó con tu secreto del webhook, algo que una comprobación a nivel de red no puede hacer. Las entregas de webhooks provienen de un conjunto de direcciones IP que cambia con el tiempo. No dependas de listas de permitidos de IP para la autenticación. Verifica siempre el encabezado webhook-signature, tal como se describe en Verificación de firmas. Si tu firewall requiere una lista de permitidos:
  • No codifiques las direcciones de forma permanente. Los rangos cambian con el tiempo y las reglas obsoletas bloquean las entregas silenciosamente.
  • Solicita los rangos actuales a support@dodopayments.com antes de restringir un firewall.
  • Presta atención a los avisos de cambios. Cuando cambian las direcciones de entrega, notificamos por correo electrónico a los merchants afectados; aplica las actualizaciones antes de la fecha indicada.
  • Mantén activada la verificación de firmas independientemente de las reglas de red que añadas.
En las plataformas serverless y de alojamiento administrado, el filtrado de IP entrante suele no estar disponible o no ser práctico. La verificación de firmas es el control adecuado en esos entornos.
Una entrega bloqueada se considera un fallo y se reintenta según el calendario descrito en Reintentos automáticos. Si las reglas del firewall provocaron el fallo de las entregas, puedes volver a enviarlas una vez corregidas las reglas; consulta Reproducción y recuperación de mensajes.

Responder a los webhooks

Tu handler del webhook debe devolver un 2xx status code para confirmar la recepción. Cualquier otra respuesta se considera un fallo y el webhook se reintentará.

Prácticas recomendadas

  • Usa únicamente HTTPS. Los endpoints HTTP son vulnerables a la interceptación.
  • Responde inmediatamente. Devuelve un código de estado 200 de inmediato y procesa después el evento de forma asíncrona.
  • Implementa la idempotencia. Usa el encabezado webhook-id para detectar y omitir eventos duplicados.
  • Protege tu secreto. Almacena DODO_PAYMENTS_WEBHOOK_KEY en variables de entorno o en un gestor de secretos, nunca en el control de versiones.

Estructura del payload del webhook

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) en la 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 en la que ocurrió el evento.
object
requerido
Payload específico del evento que contiene información detallada sobre el evento.

Ejemplo de payload

Event Types

Explora todos los tipos de eventos de webhook disponibles

Event Payloads

Consulta esquemas de payload detallados para cada evento

Handle Payment Failures

Responde a payment.failed y recupera pagos rechazados

Probar webhooks

Enviar un evento de ejemplo

Prueba la integración de tu webhook directamente desde el panel:
1

Navigate to Webhooks

Ve a Developer → Webhooks y haz clic en tu endpoint.
2

Open Testing Tab

Haz clic en la pestaña Testing.
3

Send Example

Selecciona un tipo de evento y 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 manera.
4

Check Your Endpoint

Confirma que el evento llegó, que la verificación de la firma se realizó correctamente y que devolviste un código de estado 2xx.
Los mensajes fallidos enviados desde la pestaña Testing se reintentan según el calendario normal de reintentos, como cualquier otro webhook.

Ejemplo de implementación

Implementación completa en Express.js con verificación y gestión de webhooks:
Prueba exhaustivamente tu handler del webhook mediante la interfaz de pruebas del panel antes de procesar eventos de producción. Esto ayuda a identificar y corregir los problemas de forma temprana.

Probar webhooks con la CLI

La CLI de Dodo Payments tiene dos comandos para probar webhooks durante el desarrollo local.

Escuchar webhooks en tiempo real localmente

Reenvía eventos de webhook reales desde tu cuenta en modo de prueba a tu servidor de desarrollo local:
La CLI abre una conexión WebSocket y reenvía cada evento de webhook a tu endpoint local (por ejemplo, http://localhost:3000/webhook), conservando todos los encabezados para probar la verificación de firmas.
El listener solo funciona con API keys del modo de prueba. Ejecuta dodo login y selecciona primero Test Mode.

Activar eventos de webhook simulados

Envía payloads de webhook 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. Se repite para que puedas probar varios eventos en una misma sesión. El comando de activación incluye las familias de suscripciones, pagos, reembolsos, disputas, claves de licencia, payouts, créditos, checkouts abandonados, dunning y concesiones de entitlements. No envía subscription.past_due ni subscription.unpaused. Consulta Eventos de webhook compatibles para ver la lista exacta.
Los payloads de webhook simulados de dodo wh trigger no están firmados. Usa el método de análisis no verificado (unsafeUnwrap en TypeScript, unsafe_unwrap en Python, UnsafeUnwrap en Go) en tu handler del 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 ofrece 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. De forma predeterminada, los webhooks no tienen ningún límite de velocidad aplicado y los eventos se entregan tan pronto como ocurren.
1

Open Advanced Tab

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

Configure Rate Limit

Expande la sección Endpoint throttling.
3

Set Your Limit

Introduce el número máximo de mensajes por segundo y haz clic en Save. Las entregas que superen esta velocidad se ponen en cola en lugar de descartarse.

Encabezados personalizados

Añade encabezados HTTP personalizados a todas las solicitudes de webhook enviadas a tu endpoint. Resulta útil para la autenticación, el enrutamiento o la adición de metadatos.
1

Add Headers

En la sección Custom headers, introduce un nombre y un valor de encabezado.
2

Add Multiple Headers

Haz clic en Add header para cada encabezado adicional y, después, haz clic en Save.

Transformaciones

Las transformaciones te permiten modificar el payload de un webhook y, opcionalmente, redirigirlo a una URL diferente. Usa transformaciones para:
  • Modificar la estructura del payload antes de procesarlo
  • Enrutar los webhooks a distintos endpoints según el contenido
  • Añadir o eliminar campos del payload
  • Transformar formatos de datos
1

Enable Transformations

En la sección Transformation, activa Enable transformation.
2

Configure Transformation

Escribe tus reglas de transformación en JavaScript en el editor de código y haz clic en Save. El código debe devolver el objeto de webhook desde handler().
3

Test Transformation

Usa la interfaz de pruebas de transformación para comprobar que la transformación funciona correctamente antes de ponerla en producción.
Las transformaciones pueden afectar al rendimiento de la entrega de webhooks. Realiza pruebas exhaustivas y mantén la lógica de transformación sencilla y eficiente.

Supervisar los registros de webhooks

La pestaña Logs proporciona visibilidad sobre el estado de entrega de tus webhooks.
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 la página de detalles del mensaje, que muestra:
  • El payload completo del webhook
  • Cada intento de entrega con el código de respuesta y la duración
  • La marca de tiempo de cada intento
  • Cualquier mensaje de error de tu endpoint
Cada intento incluye una acción Replay para volver a enviar ese mensaje sin salir de la página.

Supervisión de 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) en la pestaña Overview resume la misma información del último día.
La columna Error rate (24h) de la pestaña Endpoints muestra de un vistazo qué endpoints requieren atención.

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.
  • Un intervalo de mensajes — abre el endpoint, ya que los modos en bloque actúan sobre un solo endpoint cada vez.

Reproducción en bloque

Abre el endpoint desde Developer → Webhooks. Hay tres modos disponibles, cada uno de los cuales actúa únicamente sobre ese endpoint:
1

Open More Actions

En el endpoint, abre More actions y selecciona uno de los tres modos anteriores.
2

Set the Range

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

Alertas por correo electrónico

El panel de webhooks no ofrece alertas por correo electrónico para las entregas fallidas. Para supervisar las entregas, ve a Developer → Webhooks y consulta las pestañas Logs y Activity.

Implementar en plataformas cloud

Guías específicas de cada plataforma para implementar handlers de webhooks en proveedores cloud populares:

Vercel

Implementa webhooks en Vercel con funciones serverless

Cloudflare Workers

Ejecuta webhooks en la red perimetral de Cloudflare

Supabase Edge Functions

Integra webhooks con Supabase

Netlify Functions

Implementa webhooks como funciones serverless de Netlify

Referencia de API relacionada

Create Webhook

Crea y configura endpoints de webhook mediante programación

List Webhooks

Recupera y gestiona tus endpoints de webhook
Última modificación el 26 de septiembre de 2026