
Nuestra implementación de webhooks sigue la especificación de Standard Webhooks, lo que garantiza compatibilidad con las mejores prácticas de la industria y las bibliotecas de webhooks existentes.
Características clave
Real-time Delivery
Recibe notificaciones instantáneas cuando ocurren eventos
Secure by Default
Verificación de firma HMAC SHA256 incluida
Automatic Retries
Lógica de reintentos integrada con retroceso exponencial
Event Filtering
Suscríbete únicamente a los eventos que necesitas
Comenzando
Select Events to Receive
Elige los eventos específicos que debe escuchar tu endpoint de webhook seleccionándolos de la lista de eventos.
Get Secret Key
Obtén tu
Secret Key de webhook desde la página de configuración. Lo usarás para verificar la autenticidad de los webhooks recibidos.Configurando eventos suscritos
Puedes configurar qué eventos específicos deseas recibir para cada endpoint de webhook.Accediendo a la configuración de eventos
Gestionando suscripciones de eventos
View Available Events
La interfaz muestra todos los eventos de webhook disponibles organizados en una estructura jerárquica. Los eventos se agrupan por categoría (p. ej.,
dispute, payment, subscription).Search and Filter
Usa la barra de búsqueda para encontrar rápidamente eventos específicos escribiendo nombres de eventos o palabras clave.
Select Events
Marca las casillas junto a los eventos que deseas recibir. Puedes:
- Seleccionar subeventos individuales (p. ej.,
dispute.accepted,dispute.challenged) - Seleccionar eventos principales para recibir todos los subeventos relacionados
- Combinar eventos específicos según tus necesidades
Review Event Details
Pasa el cursor sobre el ícono de información (ⓘ) junto a cada evento para ver una descripción de cuándo se desencadena ese evento.
Entrega de Webhook
Timeouts
Los webhooks tienen una ventana de tiempo de espera de 15 segundos tanto para operaciones de conexión como de lectura. Asegúrate de que tu endpoint responda rápidamente para evitar timeouts.Reintentos automáticos
Si falla la entrega de un webhook, Dodo Payments reintenta automáticamente con retroceso exponencial para evitar abrumar tu sistema.| Intento | Retraso | Descripción |
|---|---|---|
| 1 | Inmediatamente | El primer reintento ocurre de inmediato |
| 2 | 5 segundos | Segundo intento después de un breve retraso |
| 3 | 5 minutos | Tercer intento con un retroceso aumentado |
| 4 | 30 minutos | Cuarto intento continuando el retroceso |
| 5 | 2 horas | Quinto intento con un retraso extendido |
| 6 | 5 horas | Sexto intento con un retraso más largo |
| 7 | 10 horas | Séptimo intento con el retraso máximo |
| 8 | 10 horas | Último intento - webhook marcado como fallido si no tiene éxito |
Máximo de 8 intentos de reintento 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.
Idempotencia
Cada evento de webhook incluye un encabezado únicowebhook-id. Usa este identificador para implementar idempotencia y evitar el procesamiento duplicado.
Orden de eventos
Los eventos de webhook pueden llegar fuera de orden debido a reintentos o condiciones de red. Diseña tu sistema para manejar eventos en cualquier secuencia.Recibirás la última carga útil en el momento de la entrega, sin importar cuándo se emitió originalmente el evento de webhook.
Asegurando Webhooks
Para garantizar la seguridad de tus webhooks, siempre valida las cargas útiles y utiliza HTTPS.Verificando firmas
Cada solicitud de webhook incluye un encabezadowebhook-signature, una firma HMAC SHA256 del payload del webhook y la marca de tiempo, firmada con tu clave secreta.
Verificación de SDK (recomendada)
Todos los SDK oficiales incluyen ayudantes integrados para validar y analizar de manera segura los webhooks entrantes. Hay dos métodos disponibles:unwrap(): Verifica firmas utilizando tu clave secreta de webhookunsafe_unwrap(): Analiza payloads sin verificación
Verificación manual (alternativa)
Si no estás utilizando un SDK, puedes verificar las firmas tú mismo siguiendo la especificación de Standard Webhooks:- Construye el mensaje firmado concatenando
webhook-id,webhook-timestampy la cadena sin modificarpayloadexacta, separados por puntos (.). - Calcula el HMAC SHA256 de esa cadena usando tu clave secreta de webhook del Panel.
- Compara la firma calculada con el encabezado
webhook-signature. Si coinciden, el webhook es auténtico.
Seguimos la especificación Standard Webhooks. Puedes usar sus bibliotecas para verificar firmas: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. Para los formatos de payload de eventos, consulta el Webhook Payload.
Respondiendo a Webhooks
- Tu manejador de webhooks debe devolver un código de estado
2xx status codepara reconocer la recepción del evento. - Cualquier otra respuesta se tratará como un fallo, y el webhook será reintentado.
Mejores prácticas
Use HTTPS endpoints only
Use HTTPS endpoints only
Usa siempre URLs HTTPS para los endpoints de webhook. Los endpoints HTTP son vulnerables a ataques man-in-the-middle y exponen tus datos de webhook.
Respond immediately
Respond immediately
Devuelve un código de estado
200 inmediatamente al recibir el webhook. Procesa el evento de forma asincrónica para evitar tiempos de espera.Handle duplicate events
Handle duplicate events
Implementa la idempotencia utilizando el encabezado
webhook-id para procesar de forma segura el mismo evento múltiples veces sin efectos secundarios.Secure your webhook secret
Secure your webhook secret
Almacena tu secreto de webhook de forma segura usando variables de entorno o un gestor de secretos. Nunca cometas secretos en el control de versiones.
Estructura de la carga útil de Webhook
Entender la estructura de la carga útil de webhook te ayuda a analizar y procesar eventos correctamente.Formato de solicitud
Encabezados
Identificador único para este evento de webhook. Úsalo para comprobaciones de idempotencia.
Firma HMAC SHA256 para verificar la autenticidad del webhook.
Marca de tiempo Unix (en segundos) cuando se envió el webhook.
Cuerpo de la solicitud
Identificador de negocio de Dodo Payments.
Tipo de evento que activó este webhook (por ejemplo,
payment.succeeded, subscription.active).Marca de tiempo en formato ISO 8601 de cuándo ocurrió el evento.
Payload específico del evento que contiene información detallada sobre el evento.
Ejemplo de carga útil
Event Types
Explora todos los tipos de eventos de webhook disponibles
Event Payloads
Consulta esquemas de payload detallados para cada evento
Probando Webhooks
Puedes probar tu integración de webhook directamente desde el panel de Dodo Payments para asegurarte de que tu endpoint esté funcionando correctamente antes de entrar en producción.
Accediendo a la interfaz de prueba
Probando tu Webhook
La interfaz de prueba proporciona una forma integral de probar tu endpoint de webhook:Select Event Type
Usa el menú desplegable para seleccionar el tipo específico de evento que deseas probar (p. ej.,
payment.succeeded, payment.failed, etc.).El menú desplegable contiene todos los tipos de eventos de webhook disponibles que tu endpoint puede recibir.
Review Schema and Example
La interfaz muestra tanto el Esquema (estructura de datos) como el Ejemplo (payload de muestra) para el tipo de evento seleccionado.
Verificando tu prueba
Check Your Endpoint
Supervisa los registros de tu endpoint de webhook para confirmar que el evento de prueba se recibió.
Verify Signature
Asegúrate de que la verificación de firma funcione correctamente con el payload de prueba.
Ejemplo de implementación
Aquí hay una implementación completa de Express.js que muestra la verificación y el manejo de webhooks:Testing Webhooks with the CLI
The Dodo Payments CLI proporciona dos comandos para probar webhooks durante el desarrollo local, sin necesidad de salir de tu terminal.Listen for Live Webhooks Locally
Reenvía eventos de webhook reales de tu cuenta en modo prueba a tu servidor de desarrollo local en tiempo real:http://localhost:3000/webhook), preservando todos los encabezados incluidos los de firma para pruebas de verificación.
El listener solo funciona con claves API en modo prueba. Ejecuta
dodo login y selecciona Test Mode antes de usar este comando.Trigger Mock Webhook Events
Envía payloads de webhook simulados a cualquier endpoint sin crear transacciones reales:CLI Webhook Testing Docs
Consulta la documentación completa de pruebas de webhook del CLI
Advanced Settings
La pestaña Advanced Settings proporciona opciones de configuración adicionales para afinar el comportamiento de tu endpoint de webhook.Rate Limiting (Throttling)
Controla la velocidad a la que se entregan los eventos de webhook a tu endpoint para evitar sobrecargar tu sistema.Configure Rate Limit
Haz clic en el botón Edit para modificar la configuración del límite de velocidad.
Por defecto, los webhooks no tienen “Rate limit” aplicado, lo que significa que los eventos se entregan tan pronto como ocurren.
Custom Headers
Agrega encabezados HTTP personalizados a todas las solicitudes de webhook enviadas a tu endpoint. Esto es útil para autenticación, enrutamiento o agregar metadatos a tus solicitudes de webhook.Add Custom Header
En la sección “Custom Headers”, ingresa una Key y un Value para tu encabezado personalizado.
Add Multiple Headers
Haz clic en el botón + para agregar encabezados personalizados adicionales según sea necesario.
Transformations
Las transformaciones te permiten modificar el payload de un webhook y redirigirlo a una URL diferente. Esta función avanzada te permite:- Modificar la estructura del payload antes del procesamiento
- Enrutar webhooks a diferentes endpoints según el contenido
- Agregar o eliminar campos del payload
- Transformar formatos de datos
Configure Transformation
Haz clic en Edit transformation para definir tus reglas de transformación.
Puedes usar JavaScript para transformar el payload del webhook y especificar una URL de destino diferente.
Monitoring Webhook Logs
La pestaña Logs proporciona visibilidad completa del estado de entrega de tus webhooks, lo que te permite monitorear, depurar y gestionar eventos de webhook de forma efectiva.
Activity Monitoring
La pestaña Activity ofrece información en tiempo real sobre el rendimiento de entrega de tus webhooks con análisis visuales.
Email Alerts
Mantente informado sobre la salud de tus webhooks con notificaciones automáticas por correo electrónico. Cuando las entregas de webhooks comienzan a fallar o tu endpoint deja de responder, recibirás alertas por correo para que puedas resolver problemas rápidamente y mantener tus integraciones en funcionamiento.
Enable Email Alerts
Navigate to Alerting Settings
Ve al panel de Dodo Payments y navega a Dashboard → Webhooks → Alerting.
Enable Email Notifications
Activa Email notifications para empezar a recibir alertas sobre problemas de entrega de webhooks.
Deploy to Cloud Platforms
¿Listo para desplegar tu manejador de webhooks en producción? Ofrecemos guías específicas por plataforma para ayudarte a desplegar webhooks en proveedores de nube populares con las mejores prácticas para cada plataforma.Vercel
Despliega 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
Despliega webhooks como funciones serverless de Netlify
Cada guía de plataforma incluye configuración de entorno, verificación de firmas y pasos de despliegue específicos para ese proveedor.
