> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trophy.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Inicio rápido
> Comienza a recibir eventos de webhook desde Trophy en menos de 10 minutos.
Primeros pasos
Si aún no tienes una cuenta de Trophy, sigue primero la [guía de inicio rápido
de Trophy](/es/getting-started/quickstart) para comenzar.
En Trophy puedes tener múltiples webhooks para gestionar uno o más tipos de eventos. Sigue los pasos a continuación para comenzar a recibir eventos de webhook desde Trophy.
Para desarrollar y probar webhooks, es útil usar un servicio de prueba que pueda reenviar eventos desde Trophy a tu entorno de desarrollo local.
Puedes elegir cualquier herramienta de desarrollo de webhooks que prefieras, pero recomendamos [Hookdeck Console](https://console.hookdeck.com).
Primero, accede a tu plataforma de prueba de webhooks preferida y crea un nuevo endpoint de prueba.
Luego, configura este endpoint para reenviar los eventos que recibe a tu entorno de desarrollo local.
Una vez que tengas tu endpoint de prueba, dirígete a la página de [webhooks](https://app.trophy.so/integration/webhooks) del panel de Trophy y crea un nuevo webhook.
* Asigna a tu nuevo webhook un nombre como 'Pruebas locales' o similar
* Pega el URL de tu endpoint de prueba en el campo 'URL del webhook'
* Selecciona los eventos de webhook a los que quieres suscribir este webhook
* Guarda el nuevo webhook
Puedes modificar los eventos a los que está suscrito el webhook en cualquier momento después de la creación.
Un manejador de webhook es simplemente un endpoint HTTP estándar capaz de recibir solicitudes `POST`.
Trophy enviará solicitudes a tu manejador, indicándole qué `type` de evento está enviando. Esto te permite construir un manejador que puede procesar múltiples tipos de eventos.
Depende de ti cómo elijas escribir tu manejador, pero un patrón común es usar una instrucción `switch`.
Aquí hay un ejemplo de este patrón en NodeJS:
```js Handling Webhook Events theme={null}
switch (payload.type) {
case "achievement.completed":
// Handle achievement completed events
break;
case "leaderboard.started":
// Handle leaderboard started events
break;
case "points.changed":
// Handle points changed events
break;
case "points.level_changed":
// Handle points level changed events
break;
default:
// Handle unrecognised event type
break;
}
```
Asegúrate de que tu manejador de webhook esté configurado para devolver un código de estado `200`. Si Trophy detecta que tu manejador devuelve un código de estado que no es `2XX`, lo tratará como un fallo e [intentará la solicitud nuevamente](/es/webhooks/retries).
Una vez que hayas escrito y asegurado tu manejador, estás listo para enviar tu primer evento de prueba.
Usando un usuario de prueba, realiza interacciones en tu producto del tipo para el que deseas probar los webhooks. Por ejemplo, si deseas probar el webhook `achievement.completed`, activa la finalización de un logro en Trophy.
Trophy enviará los eventos relevantes a tu URL de webhook y deberías verlos en tu herramienta de prueba de webhooks. Esto luego reenviará el evento a tu manejador de webhook local, activando la ejecución de tu código.
Ahora puedes iterar en tu código hasta que estés satisfecho de tener la funcionalidad que deseas.
Para ayudarte a asegurar tu manejador de webhook de modo que solo responda a eventos enviados desde Trophy y no de atacantes maliciosos, Trophy incluye una firma de webhook con cada evento.
Esta firma se envía en el encabezado `X-Trophy-Signature` y es un hash codificado en `base64` de la carga útil de la solicitud, hasheado utilizando un secreto de webhook seguro proporcionado por Trophy.
Para validar que los eventos que recibe tu controlador de webhook provienen realmente de Trophy, necesitas crear tu propio hash usando tu secreto de webhook seguro y compararlo con la firma en el encabezado `X-Trophy-Signature`.
Obtén tu secreto de webhook seguro desde la página de webhooks en Trophy.
Asegúrate de almacenar tu secreto de webhook en una variable de entorno segura y
no lo confirmes en el control de versiones.
Una vez que tengas tu secreto de webhook, estarás listo para comenzar a validar eventos. Aquí hay un ejemplo en Node.js:
```js Validating Webhook Events theme={null}
// Extract X-Trophy-Signature header from the request
const hmacHeader = request.headers.get("X-Trophy-Signature");
// Create a hash based on the parsed body
const hash = crypto
.createHmac("sha256", process.env.TROPHY_WEBHOOK_SECRET as string)
.update(await request.text())
.digest("base64");
// Compare the created hash with the value of the X-Trophy-Signature header
if (hash === hmacHeader) {
console.log("Webhook is originating from Trophy");
// Request validated, continue processing
} else {
console.log("Signature is invalid, rejected");
// Request is not from Trophy, reject with 4XX status
}
```
Si tu controlador detecta una solicitud que no se originó en Trophy, es
importante rechazar la solicitud lo antes posible con un código de estado `4XX`.
Una vez que estés satisfecho con la funcionalidad de tu webhook de prueba, crea un webhook completamente nuevo en Trophy con la misma configuración que tu webhook de prueba, pero esta vez con la URL de tu controlador de producción.
Cada webhook en Trophy tiene un secreto de webhook único, así que no olvides agregar esto como una nueva variable de entorno en tu despliegue de producción.
Ejemplo Completo de Webhook
Aquí hay un ejemplo completo funcional de un endpoint de webhook en Next.js capaz de recibir de forma segura eventos de webhook desde Trophy.
```ts Example NextJS Webhook Endpoint theme={null}
import crypto from "crypto";
import { NextRequest, NextResponse } from "next/server";
interface WebhookPayload {
type: string;
[x: string]: unknown;
}
export async function POST(request: NextRequest) {
// Extract 'X-Trophy-Signature' header from the request
const hmacHeader = request.headers.get("X-Trophy-Signature");
// Create a hash based on the parsed body
const hash = crypto
// copy this secret from the Webhooks page in Trophy
.createHmac("sha256", process.env.TROPHY_WEBHOOK_SECRET as string)
.update(await request.text())
.digest("base64");
// Compare the created hash with the value of the X-Trophy-Signature header
if (hash === hmacHeader) {
console.log("Webhook is originating from Trophy");
handleEvent(request.body as unknown as WebhookPayload);
return NextResponse.json({ message: "Webhook received" }, { status: 200 });
} else {
console.log("Signature is invalid, rejected");
return NextResponse.json({ message: "Webhook rejected" }, { status: 403 });
}
}
function handleEvent(payload: WebhookPayload) {
switch (payload.type) {
case "points.changed":
console.log("Handling points changed event");
break;
case "points.level_changed":
console.log("Handling points level changed event");
break;
case "streak.extended":
console.log("Handling streak extended event");
break;
default:
break;
}
}
```
Obtener Soporte
¿Quieres ponerte en contacto con el equipo de Trophy? Contáctanos por [correo electrónico](mailto:support@trophy.so). ¡Estamos aquí para ayudarte!
