Topgg.Integrations 0.1.0

Topgg.Integrations

Build installable Top.gg integrations in ASP.NET Core.

Top.gg integrations let users connect your service to their project with one click. Instead of manually configuring a webhook URL, Top.gg performs a handshake with your service (integration.create), stores your webhook configuration, and then delivers signed webhook events to you. When the user disconnects, Top.gg sends integration.delete.

This library handles the entire handshake for you: receive and validate the connection, persist it, respond with the correct webhook payload, clean up on disconnect, and verify signatures on every delivered event.

Install

dotnet add package Topgg.Integrations

Quick start

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddTopggIntegrations(options =>
{
    // The URL Top.gg will POST integration.create/delete to.
    options.ConfigPath = "/api/integrations/config";

    // The webhook URL Top.gg will deliver events to for each connection.
    options.WebhookUrl = "https://your.bot/api/integrations/events";

    // The event scopes you subscribe to.
    options.Scopes = new[] { "vote.create" };
});

var app = builder.Build();

// Handle the integration.create/integration.delete handshake.
app.MapTopggIntegrations();

app.Run();

That's it. MapTopggIntegrations() exposes the handshake endpoint, stores each connection (with its connection_id and webhook_secret), and returns the exact payload Top.gg expects.

Handling delivered webhook events

Webhook events are delivered to your WebhookUrl, signed with each connection's secret. Verify them with WebhookSignature:

app.MapPost("/api/integrations/events", async (HttpContext context) =>
{
    using var reader = new StreamReader(context.Request.Body);
    var rawBody = await reader.ReadToEndAsync();

    var options = context.RequestServices
        .GetRequiredService<IOptions<TopggIntegrationOptions>>().Value;

    if (!WebhookSignature.IsValid(
            options.WebhookSecret!,                       // the connection's whs_ secret
            rawBody,
            context.Request.Headers["x-topgg-signature"],
            options.MaxSignatureAge))
    {
        return Results.Unauthorized();
    }

    var vote = JsonSerializer.Deserialize<VotePayload>(rawBody);
    return Results.Ok();
});

Verifying the handshake

Top.gg may sign handshake requests to your config URL as well. Enable RequireSignature and provide your secret:

options.RequireSignature = true;
options.WebhookSecret = "whs_your_handshake_secret";

Every inbound request is then checked with constant-time HMAC SHA-256 verification before any connection is stored. MaxSignatureAge (a TimeSpan) additionally rejects replayed requests older than the given window.

API overview

Configuration

TopggIntegrationOptions:

Event payloads

• IntegrationCreateEvent / IntegrationDeleteEvent — the handshake requests Top.gg sends to your ConfigPath.
• IntegrationResponse — what you return on integration.create: webhook_url and routes.

Tests

dotnet test

License

MIT