
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
Go to Developer → Webhooks
Click Add Endpoint
Enter Your Endpoint URL
Select Events
Save
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: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.Configurar eventos suscritos
Configura qué eventos recibe cada endpoint de webhook.Navigate to Webhook Endpoints
Open Event Configuration
Select Events
payment, subscription, dispute). Marca las casillas junto a los eventos que quieres recibir. Puedes seleccionar eventos individuales, un recurso completo o combinarlos.Save Configuration
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
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 estado200 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:Idempotencia
Cada webhook incluye un encabezadowebhook-id único. Almacena este ID para detectar y omitir eventos duplicados, ya que los reintentos pueden entregar 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 campotimestamp; ú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 encabezadowebhook-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. ConfiguraDODO_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.
unwrap / unsafeUnwrap en TypeScript, unwrap / unsafe_unwrap en Python y Unwrap / UnsafeUnwrap en Go.
Verificación manual (alternativa)
Si no usas un SDK, verifica la firma por tu cuenta:- Construye el contenido firmado uniendo
webhook-id,webhook-timestampy 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. - 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. - Calcula el HMAC-SHA256 del contenido firmado con la clave de firma y codifica el resultado en base64.
- El encabezado
webhook-signaturecontiene una o más firmas separadas por espacios, cada una con el formatov1,<base64-signature>. La solicitud es válida si alguna firmav1coincide con la tuya. Compara mediante una función de tiempo constante. - Rechaza la solicitud si
webhook-timestampdifiere demasiado de la hora actual para evitar ataques de repetición. Las bibliotecas de Standard Webhooks permiten 5 minutos.
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 encabezadowebhook-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.
Responder a los webhooks
Tu handler del webhook debe devolver un2xx 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
200de inmediato y procesa después el evento de forma asíncrona. - Implementa la idempotencia. Usa el encabezado
webhook-idpara detectar y omitir eventos duplicados. - Protege tu secreto. Almacena
DODO_PAYMENTS_WEBHOOK_KEYen 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
Cuerpo de la solicitud
payment.succeeded, subscription.active).Ejemplo de payload
Event Types
Event Payloads
Handle Payment Failures
payment.failed y recupera pagos rechazadosProbar webhooks
Enviar un evento de ejemplo
Prueba la integración de tu webhook directamente desde el panel:Navigate to Webhooks
Open Testing Tab
Send Example
Check Your Endpoint
2xx.Ejemplo de implementación
Implementación completa en Express.js con verificación y gestión de webhooks: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:http://localhost:3000/webhook), conservando todos los encabezados para probar la verificación de firmas.
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:subscription.past_due ni subscription.unpaused. Consulta Eventos de webhook compatibles para ver la lista exacta.
CLI Webhook Testing Docs
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.Open Advanced Tab
Configure Rate Limit
Set Your Limit
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.Add Headers
Add Multiple Headers
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
Enable Transformations
Configure Transformation
handler().Test Transformation
Supervisar los registros de webhooks
La pestaña Logs proporciona visibilidad sobre el estado de entrega de tus webhooks.Navigate to Logs Tab
Browse Delivery History
Search and Filter
View Message Details
- 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
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.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:Open More Actions
Set the Range
Start the Run