---
title: Webhooks
canonical_url: "https://trophy.so/developers/webhooks"
description: "Power custom gamification integrations with Trophy webhooks. Subscribe to achievement, streak, points, and leaderboard events via HTTP POST requests."
---

# Power custom workflows using Trophy data

Subscribe to key gamification events like achievement.completed, leaderboard.finished, and streak.lost. Receive HTTP POST payloads from Trophy and trigger custom code in your application.

[Full feature documentation](https://docs.trophy.so/webhooks/introduction.md)

## Quickstart: verify and handle a webhook

Create a webhook in the Trophy dashboard, point it at your endpoint, and verify the X-Trophy-Signature header on every request before handling the event.

```ts
import crypto from "crypto";
import { NextRequest, NextResponse } from "next/server";

export async function POST(request: NextRequest) {
  const signature = request.headers.get("X-Trophy-Signature");
  const body = await request.text();

  const hash = crypto
    .createHmac("sha256", process.env.TROPHY_WEBHOOK_SECRET!)
    .update(body)
    .digest("base64");

  if (hash !== signature) {
    return NextResponse.json({ message: "Rejected" }, { status: 403 });
  }

  const payload = JSON.parse(body);

  switch (payload.type) {
    case "achievement.completed":
      // Handle achievement completed
      break;
    case "streak.lost":
      // Handle streak lost
      break;
    case "leaderboard.finished":
      // Handle leaderboard finished
      break;
    default:
      break;
  }

  return NextResponse.json({ message: "Received" }, { status: 200 });
}
```

## Code examples

### webhook-handler.ts

```ts
// Next.js App Router webhook handler
import crypto from "crypto";
import { NextRequest, NextResponse } from "next/server";

export async function POST(request: NextRequest) {
  const signature = request.headers.get("X-Trophy-Signature");
  const body = await request.text();

  const hash = crypto
    .createHmac("sha256", process.env.TROPHY_WEBHOOK_SECRET!)
    .update(body)
    .digest("base64");

  if (hash !== signature) {
    return NextResponse.json({ message: "Rejected" }, { status: 403 });
  }

  const payload = JSON.parse(body);

  switch (payload.type) {
    case "achievement.completed":
      // Handle achievement completed
      break;
    case "leaderboard.finished":
      // Handle leaderboard finished
      break;
    case "streak.lost":
      // Handle streak lost
      break;
    default:
      break;
  }

  return NextResponse.json({ message: "Received" }, { status: 200 });
}
```

### verify-signature.ts

```ts
// Verify X-Trophy-Signature on incoming requests
const signature = request.headers.get("X-Trophy-Signature");
const body = await request.text();

const hash = crypto
  .createHmac("sha256", process.env.TROPHY_WEBHOOK_SECRET!)
  .update(body)
  .digest("base64");

if (hash !== signature) {
  return new Response("Invalid signature", { status: 403 });
}
```

## FAQ

### How do I integrate gamification into my app without building event pipelines from scratch?

Trophy ships achievements, streaks, points, and leaderboards out of the box — then pushes real-time events to your stack with webhooks. Point an endpoint at your backend, choose the events you care about, and trigger custom logic the moment users hit milestones. Most teams are live in under a week instead of spending months on in-house infrastructure.

### Can I trigger custom emails or push notifications when users earn achievements or lose streaks?

Yes. Subscribe to events like achievement.completed, streak.lost, and points.level_changed to fire lifecycle emails, push notifications, or in-app messages from your own systems. Trophy handles gamification logic and delivery; you keep full control of copy, channels, and timing — without bolting polling or cron jobs onto your product.

### How do I sync gamification data to my data warehouse or analytics tools?

Stream Trophy webhook events into Snowflake, BigQuery, Redshift, Mixpanel, Amplitude, or any HTTP-friendly destination. Every payload carries structured gamification activity — completions, rank changes, point awards, streak breaks — so product and growth teams can analyze retention alongside the rest of your product data, not in a silo.

### Can I connect gamification to billing, feature flags, or third-party automation?

Webhooks are built for it. Teams use Trophy events to unlock paid features after milestones, update CRM records when users top a leaderboard, or route activity into Zapier, Make, and internal workflow engines. If your stack accepts HTTP POST requests, you can wire gamification into subscription, entitlement, and ops workflows without custom Trophy-specific adapters.

### Does Trophy support webhooks for leaderboards, points, and streak events?

Trophy webhooks cover the full gamification surface area: achievements, streaks (including freezes), points and levels, and leaderboard lifecycle events. Pick only the event types each endpoint needs from the dashboard. Webhooks are included on the [Pro plan](https://docs.trophy.so/account/billing#pro-plan) — built for production apps that need reliable, signed event delivery at scale.

### How fast can I add gamification webhooks to a Next.js, React, or Node.js app?

Fast. Create a webhook in the Trophy dashboard, implement a POST handler (Next.js App Router, Express, or any framework), and verify the Trophy signature on incoming requests. Use a local proxy for development, then ship the same handler to production. Follow the [quick start](https://docs.trophy.so/webhooks/quickstart) to receive your first achievement, streak, or leaderboard event in under 10 minutes.