API de votos
Pon un botón de votación en tu web y premia a tus jugadores cada vez que votan por tu hotel en HabboLibre.
- Paso 1: Tu jugador pulsa el botónEn tu web, con su nombre en el enlace:
?u=Carlos. - Paso 2: Vota en HabboLibreUn voto cada 24 horas por hotel; no necesita cuenta.
- Paso 3: Te avisamos del votoPingback: lo enviamos a tu servidor al momento. Incentive: tu servidor lo pide.
- Paso 4: Le das su premioTu servidor busca a
Carlosy le da créditos, diamantes o lo que quieras.
Lo hace tu hotelLo hace HabboLibre
El final de la dirección de tu hotel: habbolibre.org/hotels/tu-slug. Los ejemplos de la página lo usan; tu clave nunca se escribe aquí.
Hazlo con tu agente de IA
¿Programas con un agente (Claude, ChatGPT, Cursor, Codex…)? Copia este prompt y pégalo en tu agente, dentro del proyecto de tu CMS: le explica cómo recibir cada voto y premiar al jugador, y le pide que te deje elegir las piezas que quieres: el botón en tu web o en la página principal, el aviso dentro del juego, el mensaje de gracias al jugador y el panel en tu housekeeping. Es un resumen de esta misma página.
Quiero integrar en este proyecto el sistema de votos de HabboLibre (https://www.habbolibre.org), un ranking de hoteles Habbo. Este proyecto es el CMS o el servidor web de mi hotel. El objetivo es que mis jugadores voten por el hotel desde mi web o desde el juego y reciban su premio automáticamente.
DATOS DE MI HOTEL EN HABBOLIBRE
- Slug: mi-hotel
- Página de voto: https://www.habbolibre.org/hotels/mi-hotel/vote
- Documentación completa, con ejemplos en PHP, Node.js y Python (léela si puedes abrir enlaces): https://www.habbolibre.org/docs/vote-callback?hotel=mi-hotel
CÓMO FUNCIONA
1. El jugador abre mi enlace de voto, que lleva su nombre en mi hotel en el parámetro u.
2. Vota en HabboLibre: una vez cada 24 horas por hotel, sin necesidad de cuenta allí.
3. HabboLibre avisa a mi servidor con un POST (Pingback) que trae ese nombre en hotel_username.
4. Mi servidor comprueba el aviso y le da el premio.
ANTES DE ESCRIBIR CÓDIGO
Revisa cómo este proyecto define sus rutas, cómo sabe qué jugador tiene la sesión iniciada, cómo accede a la base de datos, de dónde lee su configuración y cómo se le abonan monedas u objetos a un jugador (incluido si hay que avisar al emulador para que el saldo cambie dentro del juego). Sigue esas convenciones en lugar de crear un mecanismo paralelo. Si este proyecto es Atom CMS, no lo escribas desde cero: descarga el kit https://www.habbolibre.org/downloads/habbolibre-atom-kit.zip, sigue su README y adapta solo lo que haga falta. Pregúntame lo que no puedas deducir del código, sobre todo qué premio dar por voto.
Después enséñame las opciones del apartado «QUÉ PARTES QUIERO» para que elija. Preséntalas como una lista para marcar y di cuáles recomiendas para este proyecto. Si tu herramienta permite hacer preguntas con opciones, úsala; si no, escribe la lista en el chat, pídeme los códigos que elijo (por ejemplo «W1, J1, G1, A1») y espera mi respuesta. No empieces a programar hasta que te conteste. Si te digo que decidas tú, haz las que me hayas recomendado.
Los ejemplos de la documentación enlazada son un punto de partida: si alguno difiere de lo que pido aquí, sigue lo que pido aquí.
QUÉ PARTES QUIERO
La base va siempre: recibir cada voto y dar el premio (el receptor del apartado 2 o, si mi servidor no puede recibir peticiones de fuera, Incentive del apartado 5). Lo demás son piezas sueltas; elijo las que quiera.
En mi web (el CMS)
[ ] W1. Botón «Votar en HabboLibre» en el perfil o el menú del jugador con sesión iniciada. (Recomendada)
[ ] W2. Bloque «Vota y gana» en la página principal: el premio, el botón y, si ya votó, cuándo puede volver a votar.
[ ] W3. Página propia de votos (por ejemplo /votar): si puede votar o cuánto le falta, el premio y sus últimos votos premiados.
Dentro del cliente del juego (solo si el cliente es una página web: Nitro u otro)
[ ] J1. Acceso permanente y discreto a «Votar» en la interfaz del cliente. (Recomendada si el cliente es web)
[ ] J2. Aviso pequeño en una esquina que recuerda votar a quien aún no lo hizo; va junto con J1, no en su lugar. (Recomendada si el cliente es web)
Antes de entrar al juego
[ ] P1. Puerta de voto: una pantalla que invita a votar a quien aún no lo hizo, antes de abrir el cliente, siempre con la opción de entrar sin votar. Es invasiva: hazla solo si te la pido.
Dar las gracias cuando el voto se confirma
[ ] G1. Aviso dentro del juego al jugador: «¡Gracias por votar! Recibiste 300 créditos». (Recomendada)
[ ] G2. Aviso en la web: al cargar su siguiente página o en su perfil, «Gracias por votar: +300 créditos».
En el panel de administración (housekeeping)
[ ] A1. Ajustes: activar o pausar los premios por voto, el premio y el texto de las gracias. (Recomendada)
[ ] A2. Historial: los últimos votos recibidos (fecha, jugador, premio y los que no se pudieron asociar a un jugador) y los totales de hoy y del mes.
[ ] A3. Estado de la integración: si el secreto está configurado (sin mostrarlo), cuándo llegó el último voto y la URL que debo pegar en HabboLibre.
Extras
[ ] X1. Ranking de los jugadores que más votaron este mes.
QUÉ HAY QUE CONSTRUIR
1) Dónde votan mis jugadores (piezas W1 a W3, J1, J2 y P1)
El enlace de voto es el mismo en todas:
- https://www.habbolibre.org/hotels/mi-hotel/vote?u=NOMBRE&open=1
- NOMBRE es el nombre exacto del jugador en mi hotel, codificado para URL (urlencode en PHP, encodeURIComponent en JavaScript). Máximo 100 caracteres; no admite < > comillas ni la barra invertida.
- open=1 hace que la confirmación del voto aparezca nada más llegar.
- Opcional, &ref=CODIGO: una referencia mía de 1 a 128 caracteres (letras, números y . _ ~ : -) que HabboLibre devuelve tal cual en el campo ref del aviso. Si generas un código por jugador, de un solo uso y con caducidad, y lo firmas con una clave propia del proyecto, sabrás para qué jugador se creó el enlace aunque alguien edite u (no prueba quién pulsó el botón: el premio va al jugador del código). Un ref que no cumple el formato se ignora y el voto cuenta igual.
- Se abre en una pestaña nueva normal: target="_blank" en un enlace, o window.open(url, '_blank') sin tamaño ni otras opciones. No uses una ventana emergente ni un iframe: la página no se deja incrustar, y en una ventana emergente solo muestra un paso intermedio.
En la web (W1, W2, W3)
- Solo para el jugador con sesión iniciada: sin sesión no hay nombre que poner en el enlace. A quien no tiene sesión, invítalo a entrar.
- Donde haya sitio para ello (W2 y W3), muestra si ya votó y cuándo puede volver a votar, a partir de los votos que guarda el receptor (apartado 2). HabboLibre permite un voto cada 24 horas contadas desde el último voto, no por día natural.
En el cliente del juego (J1, J2)
- J1 es una entrada integrada en la interfaz que el cliente ya tiene (el panel lateral junto al monedero o las ofertas, o el menú), con el mismo aspecto que sus otras entradas. Nada flotante que tape el juego ni su barra. Cuando el jugador ya votó, esa entrada dice cuándo puede volver a votar, o se oculta. Sin ella, quien cierra el aviso se queda sin forma de votar.
- J2 es un recordatorio que no insiste:
- aparece solo si el jugador todavía no ha votado en las últimas 24 horas;
- aparece un rato después de entrar (un minuto es buen punto de partida), nunca al abrir el cliente;
- tiene «Votar ahora» y «Ahora no»; cerrarlo lo silencia varias horas, pero nunca quita el acceso de J1.
- Para J2, la forma más corta es el aviso oficial de HabboLibre, que ya cumple esas reglas. Es este script, antes de </body> en la página del cliente; cambia {username} por la variable que imprime el nombre del jugador:
<script src="https://www.habbolibre.org/widget/vote-client.js?v=4"
data-hotel="mi-hotel"
data-user="{username}"
data-position="bottom-right"
data-theme="light"
data-accent="blue"
data-delay="60"
async></script>
- Con ese script cargado, J1 puede abrir la votación llamando a window.HabboLibreVote.open(); sin él, usa el enlace de voto de arriba.
- Si prefiero un aviso con el diseño de mi hotel, constrúyelo con esas mismas reglas. Para saber si el jugador ya votó, usa los votos que mi servidor recibió (apartado 2) o pregunta a HabboLibre: GET https://api.habbolibre.org/api/v1/hotels/mi-hotel/vote-status?u=NOMBRE responde {"voted": true o false, "next_vote_at": fecha ISO o null}. Es pública, admite un GET sin cabeceras propias desde el navegador y tiene un límite de 60 por minuto por IP; si falla, muestra el aviso igualmente. Solo sirve para no insistir a quien ya votó, no para dar premios.
Puerta de voto (P1)
- Es una pantalla intermedia en la ruta que abre el cliente, no una redirección automática a HabboLibre: muestra el premio, un botón «Votar» (el enlace de voto, en pestaña nueva) y un botón «Entrar sin votar» siempre visible.
- Solo la ve el jugador con sesión que no tiene un voto en las últimas 24 horas. Para saberlo, mira primero los votos que mi servidor recibió (apartado 2) y, si no hay ninguno, pregunta a vote-status; guarda la respuesta unos minutos por jugador para no preguntar en cada carga.
- Si esa consulta falla o tarda más de un par de segundos, deja entrar.
- Como mucho una vez al día por jugador. Después de pulsar «Votar», la pantalla ofrece «Ya voté, entrar» y deja pasar aunque el aviso de HabboLibre todavía no haya llegado.
- No la conviertas en un bloqueo sin salida. HabboLibre limita los votos por cuenta, por navegador y por red, no por nombre de jugador: quien comparte conexión con otros o ya votó desde ese navegador con otra cuenta no puede votar ese día, y se quedaría fuera del juego.
2) Receptor del Pingback
Una ruta pública, servida por HTTPS (el secreto viaja en el cuerpo), que acepte POST con cuerpo JSON, por ejemplo /api/vote-reward. No es un formulario: en PHP $_POST llega vacío y el cuerpo se lee de php://input. No lleva sesión ni token CSRF, así que exclúyela de esas protecciones y de cualquier redirección: HabboLibre no sigue redirecciones y un 301 o 302 cuenta como fallo.
Cuerpo que envía HabboLibre:
{
"vote_id": 1234,
"token": "9f2c…e81a",
"hotel_slug": "mi-hotel",
"hotel_name": "Mi Hotel",
"username": "Carlos_HL",
"hotel_username": "Carlos",
"ref": "j42.9c1f0a7e",
"user_id": 42,
"ip": "203.0.113.50",
"voted_at": "2026-11-07T19:30:00.000000Z",
"secret": "MI_PINGBACK_SECRET"
}
Reglas, en este orden:
a. Comprueba que el aviso es de HabboLibre. La forma preferida es la cabecera X-HabboLibre-Signature, con el formato t=SEGUNDOS,v1=HEX: v1 es el HMAC-SHA256 en hexadecimal de t + "." + cuerpo, con mi Pingback Secret como clave, donde cuerpo son los bytes tal como llegan, antes de decodificar el JSON. Compáralo en tiempo constante (hash_equals en PHP, crypto.timingSafeEqual en Node, hmac.compare_digest en Python) y rechaza el aviso si t se aleja más de 5 minutos de la hora actual, hacia atrás o hacia delante. La firma no evita que un aviso válido se repita dentro de ese margen: de eso se encarga la regla d. Si el proyecto no permite leer el cuerpo sin decodificar, compara al menos el campo secret con mi Pingback Secret, también en tiempo constante. Si la comprobación falla, responde 403. El secreto se lee de la variable de entorno HABBOLIBRE_PINGBACK_SECRET; si no está definida o está vacía, la ruta lo rechaza todo (un secreto vacío coincidiría con uno vacío).
b. Si llega "test": true, es el botón «Probar Pingback» de HabboLibre: responde 200 sin registrar ni premiar. Ese aviso de prueba puede traer menos campos.
c. Si hotel_slug no es "mi-hotel", responde 400.
d. Guarda vote_id en una tabla con índice único antes de premiar (INSERT que no falle si ya existe). Si ya estaba, responde 200 sin premiar otra vez: un mismo voto puede llegar hasta tres veces, porque HabboLibre lo reintenta a los 30 segundos y otra vez 2 minutos después cuando mi servidor no respondió 2xx.
e. El jugador a premiar es hotel_username, el nombre que puse en u (si decido usar ref, identifícalo solo por ref, después de comprobar mi propia firma y que no se haya usado ya; un aviso sin un ref válido se guarda entonces sin premio). Los campos username y user_id son de su cuenta de HabboLibre, que puede llamarse distinto: no los uses para abonar. Si hotel_username es null o no hay ningún jugador con ese nombre, guarda el voto sin premio y responde 200.
f. El registro del vote_id (regla d) y el abono del premio van en una misma transacción, abierta antes de insertar, para que un fallo a medias no deje un voto marcado sin premio ni un premio doble.
g. Responde 2xx en menos de 10 segundos; lo lento va después de responder.
El secreto no se escribe en el código, en el repositorio, en el JavaScript de la web ni en los logs: si registras el cuerpo para depurar, quita antes el campo secret. Y hotel_username lo escribe quien abre el enlace, así que sirve solo para saber a quién premiar.
3) Dar las gracias (piezas G1 y G2)
- Las gracias salen cuando el receptor confirmó el voto y abonó el premio, nunca cuando el jugador pulsa «Votar»: hasta que llega el aviso de HabboLibre no se sabe si votó.
- Se envían después de guardar el voto y el premio, fuera de esa transacción: si el aviso falla, el voto y el premio se quedan como están y el receptor responde 200 igual.
- G1: usa lo que ya ofrezca el emulador para hablarle a un jugador conectado (una alerta, una notificación o un mensaje, por RCON, API o la cola que use este proyecto). Si no está conectado en ese momento, no pasa nada: G2 o el historial lo cubren.
- G2: un aviso que el jugador ve una sola vez al cargar su siguiente página, o una línea en su perfil con su último voto premiado.
- El texto dice qué recibió («¡Gracias por votar! Recibiste 300 créditos») y, si hay ajustes (A1), se puede cambiar desde ahí.
4) Panel de administración (piezas A1, A2 y A3)
- Dentro del panel que ya tenga el proyecto, con sus mismos permisos: solo el personal autorizado.
- A1: activar o pausar los premios, premio por voto (por cada moneda que maneje el hotel) y texto de las gracias. Con los premios en pausa el receptor sigue guardando los votos, sin premio, y responde 200; esos votos no se premian después.
- A2: los últimos votos con fecha, jugador, premio abonado y estado (premiado, sin jugador asociado, duplicado), y los totales de hoy y del mes.
- A3: muestra si el secreto está configurado, nunca su valor; la fecha del último voto recibido; y la URL del receptor para copiarla.
- X1 (extra): los 10 jugadores con más votos premiados en el mes en curso; en un empate va primero quien llegó antes a esa cifra.
5) Solo si mi servidor no puede recibir peticiones de fuera: Incentive en lugar de Pingback
Un cron cada 1 a 5 minutos que llame a GET https://api.habbolibre.org/api/v1/hotels/mi-hotel/votes/report con las cabeceras «Authorization: Bearer» seguida del secreto y un User-Agent propio (por ejemplo MiHotel-Votes/1.0). Responde {"success": true, "count": n, "votes": [...]}; cada voto trae vote_id, username, hotel_username, ref, user_id, ip, voted_at y token. Devuelve hasta 100 votos pendientes de los últimos 30 días; si llegan 100, vuelve a llamar. Aplica las reglas d, e y f, y la pausa de A1 si existe.
- Esa llamada marca los votos como entregados en el momento de devolverlos: no vuelven a salir. Si el proceso falla después de recibirlos, recupéralos con GET https://api.habbolibre.org/api/v1/hotels/mi-hotel/votes/search (misma cabecera; acepta date=AAAA-MM-DD, username, per_page y page; no marca nada) y premia los que no tengas guardados por vote_id. No filtres ahí con unclaimed_only: esos votos ya figuran como entregados.
- El límite es de 60 peticiones por minuto: ante un 429, espera lo que indique retry_after_seconds.
- Usa uno de los dos métodos, nunca ambos: con los dos cada voto llegaría dos veces.
6) Configuración
- HABBOLIBRE_PINGBACK_SECRET en el entorno del servidor.
- El premio por voto debe poder cambiarse desde la configuración del proyecto o su panel de administración, como se haga aquí, sin tocar el código.
7) Pruebas
Prueba siempre la base y añade pruebas de las piezas que elija. De la base, cubre al menos: firma o secreto incorrectos, un aviso con la hora vencida, test en true, un voto válido que abona una sola vez, el mismo vote_id dos veces, hotel_username null o desconocido, y un cuerpo que no es JSON. Si el proyecto tiene suite de pruebas, añádelas ahí.
LO QUE HAGO YO, NO TÚ
- En HabboLibre, en Mis hoteles → Editar → Votaciones e integraciones, copio mi Pingback Secret al entorno del servidor y, si usamos Pingback, pego la URL del receptor en «URL de Pingback» y pulso «Probar Pingback».
- No me pidas el secreto en esta conversación: debe quedar solo en el servidor.
AL TERMINAR, DIME
- La URL exacta que debo pegar en «URL de Pingback» o, si usaste Incentive, cómo dejar programado el cron.
- Qué variables de entorno o ajustes tengo que definir, y dónde.
- Qué piezas hiciste, dónde quedó cada una y cómo probar el recorrido completo.
Aparte y opcional: HabboLibre también puede mostrar cuántos jugadores hay conectados en mi hotel (https://www.habbolibre.org/docs/hotel-presence?hotel=mi-hotel). No lo implementes ahora salvo que te lo pida. El prompt no lleva tu Pingback Secret y le pide al agente que no te lo pida: guárdalo tú en tu servidor, en la variable HABBOLIBRE_PINGBACK_SECRET. Revisa lo que escriba el agente antes de publicarlo y pruébalo con Probar Pingback.
¿Usas Atom CMS? Kit listo
Si tu hotel corre con Atom CMS, no hace falta programar nada: este kit trae el receptor del Pingback, el registro de votos y el premio en créditos, duckets o diamantes, sin modificar Atom. Probado con Atom 1.5.2.
Descargar el kit para Atom CMS- Copia la carpeta
app/HabboLibredel kit dentro de tu Atom. - Añade una línea en
config/app.phppara registrar el kit. - Pon en tu
.envel slug de tu hotel, tu Pingback Secret y el premio. - Limpia las cachés y ejecuta la migración.
- Pega la dirección del receptor en URL de Pingback y pulsa Probar Pingback.
El README.md del kit lo explica paso a paso, con lo opcional: el botón de votar, el aviso en el cliente, el mensaje de gracias dentro del juego, la puerta de voto (apagada de serie) y un panel en tu Housekeeping.
Botón de votación
El botón es un enlace a la página de voto de tu hotel. Añade ?u= con el nombre del jugador en tu hotel: te llega con el voto como hotel_username y sabes a quién premiar, aunque no tenga cuenta en HabboLibre.
https://www.habbolibre.org/hotels/mi-hotel/vote?u=NombreDelJugadorreftextoOpcional- Una referencia tuya, opcional: de 1 a 128 caracteres entre letras, números y
. _ ~ : -. Te la devolvemos tal cual con el voto (camporef). Sirve para saber para qué jugador creaste ese enlace aunque alguien cambieu: genera un código distinto para cada jugador, de un solo uso y con caducidad, y fírmalo con tu propia clave para que nadie pueda inventarlo. No prueba quién pulsó el botón: quien tenga el enlace de otro jugador vota en su nombre, y el premio es para ese jugador. Si no cumple el formato, se ignora y el voto cuenta igual. open1Opcional- Con
open=1la confirmación del voto aparece nada más llegar. Úsalo cuando el jugador ya pulsó «Votar» en tu web o en tu juego. utextoOpcional- Nombre del jugador en tu hotel, hasta 100 caracteres, codificado para URL (
urlencodeen PHP,encodeURIComponenten JavaScript). No admite<,>, comillas ni\. Sinu, solo sabrás quién votó si tiene cuenta en HabboLibre.
Copia el botón
<a href="https://www.habbolibre.org/hotels/mi-hotel/vote?u=NombreDelJugador" target="_blank" rel="noopener"
style="display:inline-block;padding:10px 18px;border-radius:8px;background:#2471a3;color:#ffffff;font:bold 14px/1.2 Arial,sans-serif;text-decoration:none">
Vota por nosotros en HabboLibre
</a>Cambia NombreDelJugador por el nombre de quien está viendo la página. Sin un CMS que lo rellene, quita ?u=....
Widget con tu posición
Un iframe que muestra tu puesto en el ranking, los votos del mes y si tu hotel está en línea (o cuántos jugadores hay). Todo el widget es un enlace a tu página de voto, con el ?u= que le pongas. Elige el formato con size; también puedes armarlo con el selector de Widget para tu sitio en la pestaña Widgets de la edición de tu hotel.
size=card300 × 250- Banner del hotel, puesto en el ranking, votos del mes y botón grande.
size=bar468 × 60- Puesto, banner pequeño, nombre, votos y botón en una línea.
size=leaderboard728 × 90- El formato clásico de cabecera: banner a la izquierda, datos y botón a la derecha.
size=button120 × 60- Botón de color con tu puesto.
size=mini88 × 31- El botón de 88×31 de toda la vida, en letra de píxeles.
(sin size)360 × 80, ancho fluido- Sin
size: el widget de antes, con el diseño nuevo. Cabe en los iframes ya pegados de 360×80.
Parámetros de la dirección del iframe:
sizecard | bar | leaderboard | button | miniOpcional- El formato. Sin
sizesale el widget clásico de 360 × 80, para que los iframes que ya pegaste sigan funcionando. themelight | darkOpcional- Claro u oscuro, para que combine con tu web. Los dos botones (
buttonymini) tienen un solo estilo. Por defecto:light accentblue | red | green | goldOpcional- Color del botón y del borde: azul, rojo, verde o dorado. Por defecto:
blue utextoOpcional- Nombre del jugador en tu hotel; se pasa tal cual al enlace de voto (mismas reglas que arriba). Sin
u, o con un nombre no válido, el enlace va sin nombre.
<iframe src="https://www.habbolibre.org/embed/hotels/mi-hotel?size=card&theme=light&accent=blue&u={username}" width="300" height="250" title="Votar por Mi hotel en HabboLibre" style="border:0;background:transparent" loading="lazy"></iframe>Reemplaza {username} con el nombre del jugador en tu CMS, o quita &u={username}.
Aviso en tu cliente de juego
Un script que pones en la página donde carga tu cliente. Un rato después de entrar (60 segundos, o lo que elijas) muestra un aviso «¡Vota y gana!» en una esquina y, si das premio por votar, lo anuncia. No se le muestra a quien ya votó con ese nombre en las últimas 24 horas: antes de salir lo consulta con el nombre del jugador (sin nombre, o si la consulta falla, sale igualmente). Al pulsar Votar ahora se abre en otra pestaña la página de voto de tu hotel en HabboLibre, ya con la confirmación en pantalla: el jugador vota y su juego sigue abierto. Cuando vota, el aviso no vuelve hasta que pueda votar otra vez; si pulsa Ahora no, en 6 horas.
<script src="https://www.habbolibre.org/widget/vote-client.js?v=4"
data-hotel="mi-hotel"
data-name="Mi hotel"
data-user="{username}"
data-reward="300 créditos y 3 diamantes"
data-position="bottom-right"
data-theme="light"
data-accent="blue"
data-delay="60"
async></script> Cambia {username} por la variable de tu CMS que imprime el nombre del jugador (en Atom CMS, {{ auth()->user()->username }}): llega con el voto como hotel_username, igual que con ?u=, y sabes a quién premiar. También lo armas con el generador de la pestaña Widgets de la edición de tu hotel, con un botón para probarlo.
data-hoteltextoObligatorio- El slug de tu hotel, el de su página en HabboLibre.
data-nametextoOpcional- El nombre de tu hotel, hasta 80 caracteres. Sale en el aviso.
data-usertextoOpcional- El nombre del jugador en tu hotel (
{username}es el marcador que tu CMS sustituye). Sin él, el jugador vota sin nombre y el aviso no puede saber si ya votó. data-reftextoOpcional- Tu referencia para ese jugador (ver
refen el enlace de voto): el aviso la añade al enlace y te vuelve con el voto. data-rewardtextoOpcional- El premio, hasta 120 caracteres: «300 créditos y 3 diamantes». Sale como «…y recibe 300 créditos y 3 diamantes.»
data-positionbottom-right | bottom-leftOpcional- La esquina donde aparece: abajo a la derecha o abajo a la izquierda. Por defecto:
bottom-right data-themelight | darkOpcional- Aviso claro u oscuro, para que combine con tu cliente. Por defecto:
light data-accentblue | red | green | goldOpcional- Color del botón y del borde: azul, rojo, verde o dorado (
#a56713). Por defecto:blue data-delaysegundos, de 0 a 3600Opcional- Cuánto espera el aviso antes de mostrarse desde que carga la página. Mejor un rato después de entrar que al abrir el cliente. Por defecto:
60
Deja también un acceso fijo y discreto
El aviso es un recordatorio: quien lo cierra no lo vuelve a ver en horas. Para que votar siempre esté a mano, añade una entrada «Votar» dentro de la interfaz de tu cliente (el panel lateral junto al monedero o las ofertas, o el menú), con el aspecto de las demás: nada flotante que tape el juego. Con el script cargado, esa entrada abre la votación así:
<button type="button" onclick="window.HabboLibreVote && window.HabboLibreVote.open()">
Votar
</button>¿Prefieres tu propio aviso?
Hazlo con las mismas reglas, que son las que menos molestan al jugador: un acceso discreto y permanente integrado en tu cliente, más un aviso pequeño que sale un rato después de entrar y solo a quien no ha votado. Abre el voto en una pestaña nueva (no en una ventana emergente) con &open=1 en el enlace: https://www.habbolibre.org/hotels/mi-hotel/vote?u=NombreDelJugador&open=1. La confirmación aparece al llegar y, después de votar, el jugador queda en la ficha de tu hotel.
Saber si un jugador ya votó
Para no mostrar tu aviso a quien ya votó. Es pública (sin secreto) y se puede llamar desde el navegador del jugador:
https://api.habbolibre.org/api/v1/hotels/mi-hotel/vote-status?u=NombreDelJugador{
"voted": true,
"next_vote_at": "2026-11-08T19:30:00.000000Z"
}utextoObligatorio- El nombre del jugador en tu hotel, el mismo que pones en el enlace de voto. Hasta 100 caracteres, codificado para URL.
votedbooleanotruesi votó por tu hotel con ese nombre en las últimas 24 horas.next_vote_atfecha ISO 8601 o null- 24 horas después de su último voto con ese nombre, en UTC;
nullsi no hay ninguno.
Cuenta los votos que llegaron con ese nombre en ?u=: es una ayuda para no insistir, no una comprobación de que el jugador pueda votar (eso lo decide HabboLibre al votar, por cuenta y conexión). Límite: 60 peticiones por minuto por IP. Llámala con un GET sin cabeceras propias. Si falla, muestra tu aviso igualmente. No la uses para dar premios: eso es trabajo del Pingback.
Puerta de voto antes de entrar (opcional)
Algunos hoteles enseñan una pantalla que invita a votar antes de abrir el cliente. Consigue más votos, pero interrumpe al jugador: úsala solo si de verdad la quieres, y siempre con estas reglas.
- Es una pantalla tuya con un botón Votar (el enlace de voto, en pestaña nueva) y un botón Entrar sin votar siempre a la vista. No redirijas al jugador a HabboLibre sin que lo pida.
- Solo para quien no ha votado en 24 horas: mira primero los votos que recibió tu servidor y, si no tienes ninguno, consulta la dirección de arriba. Guarda la respuesta unos minutos.
- Si la consulta falla o tarda, deja entrar.
- Como mucho una vez al día por jugador.
Pingback o Incentive
Hay dos formas de que tu servidor se entere de cada voto. Elige una sola: con las dos, cada voto te llegaría dos veces.
Pingback Recomendado
HabboLibre envía cada voto a tu servidor en cuanto ocurre.
- Cuándo te llega
- En segundos.
- Qué necesitas
- Una URL pública que acepte
POST. - Si tu servidor falla
- Lo reintentamos 2 veces más en los 3 minutos siguientes.
Incentive
Tu servidor pregunta por los votos nuevos cada pocos minutos.
- Cuándo te llega
- Cuando corra tu cron (cada 1 a 5 minutos es lo normal).
- Qué necesitas
- Un cron o un proceso que llame a la API; tu servidor no recibe nada de fuera.
- Si tu servidor falla
- Los votos esperan 30 días hasta que los pidas.
Pingback: configurar
Paso 1: Prepara una dirección en tu web
Una URL pública que acepte
POSTcon JSON, por ejemplohttps://mihotel.com/api/vote-reward. Tienes el código en Pingback: código.Tiene que ser
https://: el secreto viaja en el cuerpo y no lo enviamos sin cifrar. No seguimos redirecciones, así que pon la dirección final.Paso 2: Guárdala en tu hotel
En Mis hoteles → Editar → Votaciones e integraciones, pégala en URL de Pingback y guarda.
Paso 3: Copia el secreto a tu servidor
En el mismo bloque está tu Pingback Secret. Guárdalo en tu servidor (una variable de entorno, no en el código) para comprobar que cada aviso viene de HabboLibre.
Paso 4: Pruébalo
Pulsa Probar Pingback. Enviamos un voto de prueba con
"test": truey el jugadorTestPlayer, y te mostramos el código HTTP y el principio de lo que respondió tu servidor.
Pingback: datos del voto
Cada voto llega a tu URL como un POST con cuerpo JSON:
POST /api/vote-reward HTTP/1.1
Host: mihotel.com
Content-Type: application/json
User-Agent: GuzzleHttp/7
X-HabboLibre-Signature: t=1794166200,v1=5d41…c3a9
{
"vote_id": 1234,
"token": "9f2c…e81a",
"hotel_slug": "mi-hotel",
"hotel_name": "Mi Hotel",
"username": "Carlos_HL",
"hotel_username": "Carlos",
"ref": "j42.9c1f0a7e",
"user_id": 42,
"ip": "203.0.113.50",
"voted_at": "2026-11-07T19:30:00.000000Z",
"secret": "TU_PINGBACK_SECRET"
}$_POST llega vacío: lee json_decode(file_get_contents('php://input'), true). En Laravel, $request->input() ya lo lee. vote_identero- Identificador único del voto. Úsalo para no premiar dos veces.
tokentexto- Código del voto, 64 caracteres.
hotel_slugtexto- El slug de tu hotel.
hotel_nametexto- El nombre de tu hotel.
usernametexto o null- Su nombre en HabboLibre;
nullsi votó sin cuenta. No premies con él: puede no ser su nombre en tu hotel. hotel_usernametexto o null- Su nombre en tu hotel, del
?u=del enlace;nullsi votó sin él. reftexto o null- Tu referencia, la del
&ref=del enlace, tal cual la enviaste;nullsi el enlace no la llevaba o no cumplía el formato. user_identero o null- Su id en HabboLibre;
nullsi votó sin cuenta. iptexto- IP desde la que votó.
voted_atfecha ISO 8601- Cuándo votó, en UTC.
secrettexto- Tu Pingback Secret. Compáralo siempre antes de premiar.
testbooleano- Solo en el voto de prueba del botón Probar Pingback:
true. No premies.
Comprueba la firma (recomendado)
Cada aviso lleva la cabecera X-HabboLibre-Signature: t=…,v1=…. t es la hora del envío en segundos Unix y v1 es el HMAC-SHA256, en hexadecimal, de t + "." + cuerpo con tu Pingback Secret como clave, donde el cuerpo son los bytes tal como llegan, antes de decodificar el JSON. Comprobarla demuestra que el aviso es nuestro y que nadie lo cambió, y descartar los que tengan más de 5 minutos impide que alguien reenvíe uno antiguo. Dentro de esos 5 minutos un aviso sí puede repetirse: de eso te protege guardar cada vote_id una sola vez.
<?php
$body = file_get_contents('php://input'); // los bytes tal como llegan
$header = $_SERVER['HTTP_X_HABBOLIBRE_SIGNATURE'] ?? '';
if (!preg_match('/^t=([0-9]+),v1=([0-9a-f]{64})$/D', $header, $m)) {
http_response_code(403);
exit('Missing signature');
}
[, $t, $v1] = $m;
$secret = (string) getenv('HABBOLIBRE_PINGBACK_SECRET');
if ($secret === '') { // sin secreto configurado, no se acepta nada
http_response_code(503);
exit('Not configured');
}
$expected = hash_hmac('sha256', $t . '.' . $body, $secret);
if (!hash_equals($expected, $v1) || abs(time() - (int) $t) > 300) {
http_response_code(403);
exit('Invalid signature');
}
$vote = json_decode($body, true); // a partir de aquí, como en el ejemplo de abajo El campo secret del cuerpo sigue llegando como siempre, así que una integración que solo lo compara no deja de funcionar. Cada reintento lleva una hora y una firma nuevas.
Pingback: respuesta y reintentos
Responde con un código 2xx en menos de 10 segundos. Cualquier otra cosa cuenta como fallo: un 4xx o 5xx, un tiempo agotado y también una redirección (301, 302), porque no las seguimos.
Al momento
Primer envío, en cuanto el jugador vota.
30 segundos después
Segundo intento, si el primero falló.
2 minutos después del segundo
Tercer y último intento.
Después
El voto queda sin entregar. Lo ves con
/votes/search?unclaimed_only=1y puedes premiarlo a mano.
vote_id con un índice UNIQUE y, si ya lo tenías, responde 200 sin premiar de nuevo. Pingback: código
Los tres ejemplos hacen lo mismo: comprueban el secreto, ignoran la prueba, descartan duplicados y premian.
<?php
// El cuerpo es JSON: $_POST llega vacío, se lee de php://input.
$vote = json_decode(file_get_contents('php://input'), true);
if (!is_array($vote) || !isset($vote['secret'], $vote['vote_id'])) {
http_response_code(400);
exit('Invalid payload');
}
// 1. ¿Viene de HabboLibre? hash_equals compara sin filtrar tiempos.
// Sin secreto configurado no se acepta nada: un secreto vacío coincidiría con uno vacío.
$secret = (string) getenv('HABBOLIBRE_PINGBACK_SECRET');
if ($secret === '' || !hash_equals($secret, (string) $vote['secret'])) {
http_response_code(403);
exit('Invalid secret');
}
// 2. El botón "Probar Pingback" manda test=true: responde sin premiar.
if (!empty($vote['test'])) {
exit('Test OK');
}
// 3. Un voto puede llegar dos veces: processed_votes.vote_id es PRIMARY KEY.
$pdo = new PDO(getenv('DB_DSN'), getenv('DB_USER'), getenv('DB_PASS'));
$insert = $pdo->prepare('INSERT IGNORE INTO processed_votes (vote_id) VALUES (?)');
$insert->execute([$vote['vote_id']]);
if ($insert->rowCount() === 0) {
exit('Already processed');
}
// 4. Premia a hotel_username: su nombre en tu hotel, el del ?u= del enlace.
// username es su cuenta de HabboLibre y puede llamarse distinto: no premies con ella.
$player = $vote['hotel_username'] ?? null;
if ($player !== null) {
giveVoteReward($pdo, $player); // tu función: créditos, diamantes, furni...
}
echo 'OK';CREATE TABLE processed_votes (
vote_id INT UNSIGNED NOT NULL PRIMARY KEY,
processed_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);Incentive: votos pendientes
Con Incentive tu servidor pregunta cada pocos minutos por los votos nuevos. Útil si tu servidor no puede recibir peticiones de fuera. Te identificas con tu Pingback Secret:
Authorization: Bearer TU_PINGBACK_SECREThttps://api.habbolibre.org/api/v1/hotels/mi-hotel/votes/report- Devuelve hasta 100 votos pendientes de los últimos 30 días, del más antiguo al más nuevo.
- Los marca como entregados: cada voto sale una sola vez. Si recibes 100, vuelve a llamar hasta que lleguen menos.
- Si tu script falla después de recibirlos, recupéralos con Buscar votos.
{
"success": true,
"count": 1,
"votes": [
{
"vote_id": 1234,
"username": "Carlos_HL",
"hotel_username": "Carlos",
"ref": "j42.9c1f0a7e",
"user_id": 42,
"ip": "203.0.113.50",
"voted_at": "2026-11-07T19:30:00.000000Z",
"token": "9f2c…e81a"
}
]
}countentero- Votos de esta respuesta (máximo 100).
votes[]lista- Cada voto con
vote_id,username,hotel_username,ref,user_id,ip,voted_atytoken, como en el Pingback.
Errores
HTTP 401Invalid API key.- Falta la cabecera
Authorizationo la clave no es la actual. HTTP 404Hotel not found.- El slug de la dirección no existe.
HTTP 429{"message", "retry_after_seconds"}- Más de 60 peticiones por minuto desde tu IP. Consultar cada 1 a 5 minutos va de sobra.
Incentive: buscar votos
Consulta los votos de los últimos 30 días sin marcarlos como entregados: para revisar un voto que un jugador reclama o para recuperar los que tu script no llegó a procesar. Del más nuevo al más antiguo.
https://api.habbolibre.org/api/v1/hotels/mi-hotel/votes/searchusernametextoOpcional- Busca por nombre: coincide con su cuenta de HabboLibre o con el
hotel_usernamedel enlace. ipIPOpcional- Votos desde esa IP.
datefechaOpcional- Votos de ese día, en formato
2026-11-07. unclaimed_onlybooleanoOpcional- Con
1, solo los votos que todavía no se entregaron. per_pageenteroOpcional- Resultados por página, de 1 a 100. Por defecto:
50 pageenteroOpcional- Página que quieres ver. Por defecto:
1
{
"success": true,
"count": 152,
"page": 1,
"last_page": 4,
"votes": [
{
"vote_id": 1234,
"username": "Carlos_HL",
"hotel_username": "Carlos",
"ref": "j42.9c1f0a7e",
"user_id": 42,
"ip": "203.0.113.50",
"voted_at": "2026-11-07T19:30:00.000000Z",
"token": "9f2c…e81a",
"is_claimed": true
}
]
}count es el total de resultados de todas las páginas. Recorre page de 1 a last_page para verlos todos.
Incentive: código
<?php
// Cron cada 5 minutos: */5 * * * * /usr/bin/php /ruta/incentive.php
$url = 'https://api.habbolibre.org/api/v1/hotels/mi-hotel/votes/report';
do {
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('HABBOLIBRE_PINGBACK_SECRET'),
'Accept: application/json',
'User-Agent: MiHotel-Incentive/1.0',
],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status !== 200) {
fwrite(STDERR, "HabboLibre respondió HTTP {$status}: {$body}\n");
exit(1);
}
$data = json_decode($body, true);
foreach ($data['votes'] as $vote) {
// Premia a hotel_username (su nombre en tu hotel, del ?u=), nunca a username (su cuenta de HabboLibre)
$player = $vote['hotel_username'] ?? null;
if ($player !== null) {
giveVoteReward($player); // tu función
}
}
} while ($data['count'] === 100); // había más: pide el siguiente loteSeguridad
- Mejor que comparar el secreto: comprueba la cabecera
X-HabboLibre-Signaturey descarta los avisos con más de 5 minutos. - Compara el secreto con
hash_equals(PHP),crypto.timingSafeEqual(Node) ohmac.compare_digest(Python), no con==: una comparación normal deja adivinarlo por el tiempo de respuesta. - Premia una sola vez por
vote_id: guárdalo con un índiceUNIQUEantes de dar la recompensa. - Premia solo a
hotel_username.usernamees su cuenta de HabboLibre: puede llamarse distinto, o igual que otro jugador de tu hotel. - No confíes en
hotel_usernamepara nada más que saber a quién premiar: lo escribe quien abre el enlace. - Cuando registres el cuerpo para depurar, quita antes el campo
secret. - El secreto solo va en tu servidor: nunca en el JavaScript de tu web ni en un repositorio público. Si se filtró, pulsa Regenerar clave en Mis hoteles → Editar y actualiza tus scripts.
Problemas frecuentes
hotel_username llega vacío
- El jugador votó desde la ficha del hotel y no desde tu enlace con
?u=: en ese caso lleganull. - Tu servidor lee
$_POST: el cuerpo es JSON, léelo dephp://input. - Para ver exactamente qué llega, guarda el cuerpo un momento, sin el secreto, y borra el archivo al terminar:
$b = json_decode(file_get_contents('php://input'), true); unset($b['secret']); file_put_contents('/tmp/pingback.log', json_encode($b) . PHP_EOL, FILE_APPEND); - Si llega
null, ese voto no trae jugador de tu hotel: guárdalo sin premio. No lo sustituyas porusername.
No me llega ningún pingback
- Comprueba que la URL de Pingback está guardada y pulsa Probar Pingback: verás el código que respondió tu servidor.
- Un 301 o 302 significa que tu web redirige (de http a https, o a
www): pon la dirección final. - La dirección debe ser pública y empezar por
https://: no aceptamoshttp://,localhost, IPs privadas ni usuario y contraseña en la URL. - Si usas Cloudflare o un firewall, deja pasar los
POSTa esa ruta: el modo anti-bots puede bloquearlos.
Respondo 200, pero los reintentos siguen llegando
Tu servidor tardó más de 10 segundos y lo contamos como fallo. Responde en cuanto guardes el voto y deja lo lento (correos, varias consultas) para después.
Me llegan votos duplicados
Es posible por los reintentos. Guarda vote_id con índice UNIQUE y usa INSERT IGNORE: si no insertó nada, ese voto ya lo premiaste.
Incentive responde HTTP 403
Con el cuerpo error code: 1010, Cloudflare rechazó tu User-Agent: envía uno propio, como en los ejemplos. Con una página HTML y la cabecera cf-mitigated: challenge, Cloudflare desafió la IP de tu servidor: escríbenos con el valor de cf-ray.
¿Cada cuánto puede votar un jugador?
Una vez cada 24 horas por hotel, con o sin cuenta en HabboLibre. Además hay un límite diario de votos desde una misma conexión, para que nadie infle el ranking. Si premias por voto, no hace falta que lleves tu propio límite.
