POST que Whop envía a tu servidor cuando ocurre un evento. Ejemplos de eventos: un pago se completa correctamente, una membresía se activa, se abre una disputa. Registras una URL pública. Whop envía un evento JSON firmado a esa URL cada vez que ocurre uno de los eventos a los que estás suscrito.
Cómo es un webhook
Cada evento es una solicitudPOST:
api_version_date de tu webhook, igual que data. Los webhooks fijados antes de 2026-08-14, y los webhooks sin versión fijada, reciben el campo de cuenta como company_id en lugar de account_id.
Los encabezados de la solicitud HTTP se versionan de la misma forma: cualquier cambio futuro en los encabezados se publica como una versión de API con fecha, y tu versión fijada mantiene los encabezados con los que te integraste. Cuatro encabezados están congelados por contrato y nunca cambian en ninguna versión: webhook-id, webhook-signature, webhook-timestamp y content-type; la verificación de la firma funciona de forma idéntica en todas las versiones fijadas.
Un campo opcional del sobre describe qué cambió:
previous_attributes: presente en los eventos.updatedque capturan cambios (account.updated,product.updated,plan.updatedyshipment.updated). Es un objeto con los valores anteriores de los campos dedataque cambiaron, indexado por nombre de campo. Cambiar el nombre de la cuenta a “Shine Time Auto Detailing” entrega{"title": "Webb's Mobile Detailing"}, el valor que tenía cada campo modificado antes de la escritura. Cuando el campo no está presente, no había captura de cambios disponible para el evento. Los valores siguen la versión fijada enapi_version_datede tu webhook, igual quedata.
Recuperar un pago de suscripción
Cuando el banco pide al comprador que verifique un cargo fuera de sesión, Whop emitepayment.requires_action. Envía su data.recovery_url al comprador para que pueda iniciar sesión en Whop y completar 3D Secure para ese pago. Los checkouts en sesión nunca lo emiten, porque el comprador ya está completando la verificación. Una renovación de suscripción fallida también emite payment.failed. Consulta data.decline_code y data.failure_message para conocer el motivo cuando esté disponible, y usa también allí data.recovery_url cuando esté presente.
El mismo campo recovery_url está disponible cuando obtienes el recurso Payment. Las listas de pagos no incluyen enlaces de recuperación. Es null cuando la recuperación de la autenticación no está disponible o no tienes member:basic:read. Abrir el enlace no inicia un cargo: el comprador debe confirmar y Whop comprueba si el pago aún se puede recuperar. Tras la recuperación, sigue gestionando payment.succeeded o payment.failed para conocer el resultado.
Crear un webhook
- API
- Panel
webhook_secret. La API muestra este valor una sola vez. Guárdalo de inmediato. Consulta la referencia de la API de webhooks para ver todos los campos, incluidos resource_id (la cuenta o app propietaria del webhook) y child_resource_events. Un webhook que pertenece a una app también recibe los eventos de instalación y desinstalación de esa app. Consulta Instalaciones de apps.Verificar y gestionar eventos
Verifica siempre la firma antes de usar un payload.1
Guarda tu secreto de firma
La verificación necesita el secreto, no un cliente del SDK. Guarda el valor que devolvió la API como
WHOP_WEBHOOK_SECRET y pásalo al helper exactamente como te lo dio Whop: una cadena ws_. No quites el prefijo ni lo codifiques en base64. El helper deriva la clave.2
Gestiona los eventos en tu servidor
Una sola llamada verifica la firma y devuelve el evento analizado. Si la firma es incorrecta, la llamada lanza un error y tu handler nunca ve el payload.El helper devuelve el cuerpo analizado, no un objeto de evento tipado: un objeto plano en TypeScript, un
dict en Python y un Hash con claves de tipo símbolo en Ruby. Ramifica según type y lee data como se muestra.Verificar sin un SDK
Verificar sin un SDK
Whop firma la cadena
{webhook-id}.{webhook-timestamp}.{raw body} con HMAC-SHA256. La clave es tu secreto ws_.... El encabezado webhook-signature contiene el resultado en base64: v1,<signature>.Para verificar una solicitud: calcula el HMAC sobre el cuerpo sin procesar de la solicitud, codifica el resultado en base64 y compáralo con el valor del encabezado mediante una comparación de tiempo constante. Rechaza una solicitud si su webhook-timestamp difiere en más de 5 minutos de la hora actual. Esto evita los ataques de repetición. Los verificadores de los SDK aplican este límite automáticamente.Probar tu endpoint
- Envía un evento de prueba. En el panel, abre el menú del webhook y selecciona un evento de prueba. O llama a
POST /api/v1/webhooks/{id}/test. Whop envía un payload de ejemplo a tu URL y devuelve el estado y el cuerpo de la respuesta de tu servidor. - Examina las entregas. Whop conserva cada entrega durante 30 días: la solicitud, el código de respuesta, el cuerpo de la respuesta y los tiempos. Consulta las entregas en el panel o con
GET /api/v1/webhooks/{id}/deliveries.
Una URL de webhook debe ser accesible desde internet. Whop rechaza
localhost y las direcciones de redes privadas. Para el desarrollo local, usa ngrok o Cloudflare Tunnel para redirigir una URL pública a tu máquina. Registra la URL del túnel.Entrega
Responde con un estado 2xx en menos de 5 segundos. Todos los demás resultados son intentos fallidos: un tiempo de espera agotado, un estado de error o una redirección. Whop no sigue las redirecciones. Whop entrega cada evento al menos una vez. El mismo evento puede llegar más de una vez. Haz que tu handler sea idempotente. Cada reintento de una entrega tiene el mismowebhook-id. Guarda el webhook-id e ignora los duplicados.
Whop reintenta las entregas fallidas durante aproximadamente 3 días. Tras el primer intento, Whop reintenta 12 veces con intervalos crecientes: 30 segundos, 2 minutos, 8 minutos, 30 minutos, 1 hora, 3 horas, 6 horas y después cada 12 horas. El calendario completo dura aproximadamente 71 horas.
El orden de las entregas no está garantizado. Un evento más reciente puede llegar antes que uno más antiguo. Procesa cada evento de forma independiente. Si el orden es importante, lee el estado actual desde la API.
Whop desactiva los endpoints que siguen fallando. Si todas las entregas a tu endpoint fallan durante 24 horas, Whop envía un correo de advertencia a tu cuenta. Si los fallos continúan durante 72 horas y fallaron 10 o más entregas, Whop desactiva el webhook y envía un segundo correo. Para volver a activar el webhook, usa el panel o envía PATCH /api/v1/webhooks/{id} con "enabled": true. Esto restablece el historial de fallos. Whop no envía los eventos que ocurrieron mientras el webhook estaba desactivado. Consulta la API para encontrar los datos que te perdiste.
Solucionar problemas de entrega de webhooks
Corrige fallos de firma, reintentos, eventos duplicados y problemas con túneles locales.
Eventos y versiones
Dos campos de versión controlan los datos que recibe tu endpoint:api_version: el formato del sobre. Usav1. Esta página describe solov1. Los formatos heredadosv2yv5existen para integraciones antiguas y no usan firmas de Standard Webhooks. No los uses en integraciones nuevas.api_version_date: la versión de API con fecha que define la forma dedatay del propio sobre (por ejemplo, las versiones fijadas a partir de2026-08-14incluyenaccount_iddonde las anteriores incluyencompany_id). Funciona igual que el encabezadoApi-Version-Dateen las lecturas REST. Establécela al crear un webhook con la API. Así, la forma del payload se mantiene estable cuando la API cambia. Los webhooks sin versión fijada mantienen la forma inicial de su payload y su sobre. Excepción: los recursos que solo existen en la API actual (tarjetas, variantes, transferencias, swaps, depósitos, exportaciones) siempre reciben la forma más reciente dedata; el sobre sigue respetando la versión fijada.
resource.action. Cada evento de la tabla enlaza a una página de referencia con el esquema del payload:
Próximos pasos
Aceptar pagos
Usa los webhooks
payment.succeeded con el checkout para completar pedidos.Guardar métodos de pago
Usa setup intents y webhooks para cobrar a los clientes más tarde.
Inicio rápido
Descubre cómo funcionan los webhooks con el checkout, las transferencias y KYC.
Referencia de la API de webhooks
Todos los endpoints y campos: crear, actualizar, probar, entregas.

