Skip to main content
Un webhook es una solicitud 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.
Los webhooks de Whop usan la especificación Standard Webhooks. Los SDK de Whop verifican la firma y analizan el evento en una sola llamada. Para Go, usa Verificar sin un SDK al final de esta página.

Cómo es un webhook

Cada evento es una solicitud POST:
El sobre sigue la versión fijada en 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 .updated que capturan cambios (account.updated, product.updated, plan.updated y shipment.updated). Es un objeto con los valores anteriores de los campos de data que 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 en api_version_date de tu webhook, igual que data.

Recuperar un pago de suscripción

Cuando el banco pide al comprador que verifique un cargo fuera de sesión, Whop emite payment.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

La respuesta contiene 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.
Haz solo el trabajo necesario antes de responder: verifica el evento, pon el trabajo en una cola y devuelve 200. El ejemplo de TypeScript usa waitUntil de @vercel/functions. En otros runtimes, usa la función de tareas en segundo plano de tu framework o una cola de trabajos.
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 mismo webhook-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. Usa v1. Esta página describe solo v1. Los formatos heredados v2 y v5 existen 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 de data y del propio sobre (por ejemplo, las versiones fijadas a partir de 2026-08-14 incluyen account_id donde las anteriores incluyen company_id). Funciona igual que el encabezado Api-Version-Date en 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 de data; el sobre sigue respetando la versión fijada.
Los nombres de eventos tienen el formato 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.