feat: add webhooks

.gitignore

@@ -1,5 +1,4 @@
 *.user
-*.json
 */.vs
 .vs/
 */obj

Topgg.Sdk.Webhooks/Data/PartialProject.cs

@@ -0,0 +1,24 @@
+using System.Text.Json.Serialization;
+using Topgg.Sdk.Webhooks.Serialization;
+
+namespace Topgg.Sdk.Webhooks.Data;
+
+/// <summary>A brief information on project listed on Top.gg.</summary>
+public class PartialProject
+{
+    /// <summary>The project's ID.</summary>
+    [JsonConverter(typeof(ULongToStringConverter))]
+    public ulong Id { get; internal init; }
+
+    /// <summary>The project's ID.</summary>
+    [JsonConverter(typeof(JsonStringEnumConverter))]
+    public ProjectType Type { get; internal init; }
+
+    /// <summary>The project's platform.</summary>
+    [JsonConverter(typeof(JsonStringEnumConverter))]
+    public Platform Platform { get; internal init; }
+
+    /// <summary>The project's platform ID.</summary>
+    [JsonConverter(typeof(ULongToStringConverter))]
+    public ulong PlatformId { get; internal init; }
+}

Topgg.Sdk.Webhooks/Data/Platform.cs

@@ -0,0 +1,7 @@
+namespace Topgg.Sdk.Webhooks.Data;
+
+/// <summary>A project's platform.</summary>
+public enum Platform
+{
+    Discord
+}

Topgg.Sdk.Webhooks/Data/ProjectType.cs

@@ -0,0 +1,8 @@
+namespace Topgg.Sdk.Webhooks.Data;
+
+/// <summary>A project's type.</summary>
+public enum ProjectType
+{
+    Bot,
+    Server
+}

Topgg.Sdk.Webhooks/Data/User.cs

@@ -0,0 +1,23 @@
+using System.Text.Json.Serialization;
+using Topgg.Sdk.Webhooks.Serialization;
+
+namespace Topgg.Sdk.Webhooks.Data;
+
+/// <summary>A Top.gg user.</summary>
+public class User
+{
+    /// <summary>The user's ID.</summary>
+    [JsonConverter(typeof(ULongToStringConverter))]
+    public ulong Id { get; internal init; }
+
+    /// <summary>The user's name.</summary>
+    public string Name { get; internal init; }
+
+    /// <summary>The user's avatar URL.</summary>
+    [JsonPropertyName("avatar_url")]
+    public string Avatar { get; internal init; }
+
+    /// <summary>The user's platform ID.</summary>
+    [JsonConverter(typeof(ULongToStringConverter))]
+    public ulong PlatformId { get; internal init; }
+}

Topgg.Sdk.Webhooks/Payloads/Integration.cs

@@ -0,0 +1,31 @@
+using System.Text.Json.Serialization;
+using Topgg.Sdk.Webhooks.Data;
+using Topgg.Sdk.Webhooks.Serialization;
+
+namespace Topgg.Sdk.Webhooks.Payloads;
+
+/// <summary>An `integration.create` webhook payload.</summary>
+public class IntegrationCreatePayload
+{
+    /// <summary>The unique identifier for this connection.</summary>
+    [JsonConverter(typeof(ULongToStringConverter))]
+    public ulong ConnectionId { get; internal init; }
+
+    /// <summary>The secret used to verify future webhook deliveries.</summary>
+    [JsonPropertyName("webhook_secret")]
+    public string Secret { get; internal init; }
+
+    /// <summary>The project that the integration refers to.</summary>
+    public PartialProject Project { get; internal init; }
+
+    /// <summary>The user who triggered this event.</summary>
+    public User User { get; internal init; }
+}
+
+/// <summary>An `integration.delete` webhook payload.</summary>
+public class IntegrationDeletePayload
+{
+    /// <summary>The unique identifier for this connection.</summary>
+    [JsonConverter(typeof(ULongToStringConverter))]
+    public ulong ConnectionId { get; internal init; }
+}

Topgg.Sdk.Webhooks/Payloads/Payload.cs

@@ -0,0 +1,10 @@
+using System.Text.Json;
+
+namespace Topgg.Sdk.Webhooks.Payloads;
+
+internal class Payload
+{
+    public string Type { get; init; }
+
+    public JsonElement Data { get; init; }
+}

Topgg.Sdk.Webhooks/Payloads/Test.cs

@@ -0,0 +1,13 @@
+using Topgg.Sdk.Webhooks.Data;
+
+namespace Topgg.Sdk.Webhooks.Payloads;
+
+/// <summary>A `webhook.test` webhook payload.</summary>
+public class TestPayload
+{
+    /// <summary>The project that the test refers to.</summary>=
+    public PartialProject Project { get; internal init; }
+
+    /// <summary>The user who triggered this test.</summary>=
+    public User User { get; internal init; }
+}

Topgg.Sdk.Webhooks/Payloads/VoteCreate.cs

@@ -0,0 +1,30 @@
+using System;
+using System.Text.Json.Serialization;
+using Topgg.Sdk.Webhooks.Data;
+using Topgg.Sdk.Webhooks.Serialization;
+
+namespace Topgg.Sdk.Webhooks.Payloads;
+
+/// <summary>A `vote.create` webhook payload.</summary>
+public class VoteCreatePayload
+{
+    /// <summary>The vote's ID.</summary>
+    [JsonConverter(typeof(ULongToStringConverter))]
+    public ulong Id { get; internal init; }
+
+    /// <summary>The number of votes this vote counted for. This is a rounded integer value which determines how many points this individual vote was worth.</summary>
+    public int Weight { get; internal init; }
+
+    /// <summary>When the vote was cast.</summary>
+    [JsonPropertyName("created_at")]
+    public DateTime VotedAt { get; internal init; }
+
+    /// <summary>When the vote expires (the user can vote again.)</summary>
+    public DateTime ExpiresAt { get; internal init; }
+
+    /// <summary>The project that received this vote.</summary>
+    public PartialProject Project { get; internal init; }
+
+    /// <summary>The user who voted for this project.</summary>
+    public User User { get; internal init; }
+}

Topgg.Sdk.Webhooks/Serialization/ULongToStringConverter.cs

@@ -0,0 +1,21 @@
+using System;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Topgg.Sdk.Webhooks.Serialization;
+
+/// <summary>Converts API responses from strings to longs and vice versa.</summary>
+internal class ULongToStringConverter : JsonConverter<ulong>
+{
+    public override ulong Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+    {
+        if (reader.TokenType == JsonTokenType.String && ulong.TryParse(reader.GetString(), out var value))
+        {
+            return value;
+        }
+
+        throw new InvalidOperationException();
+    }
+
+    public override void Write(Utf8JsonWriter writer, ulong value, JsonSerializerOptions options) => writer.WriteStringValue(value.ToString());
+}

Topgg.Sdk.Webhooks/Tests/CustomWebhooks.cs

@@ -0,0 +1,24 @@
+using System;
+using System.Threading.Tasks;
+using Topgg.Sdk.Webhooks.Payloads;
+using Microsoft.AspNetCore.Http;
+
+namespace Topgg.Sdk.Webhooks.Tests;
+
+internal class CustomWebhooks() : WebhookEventListener(Mock.Secret)
+{
+    public override Task OnIntegrationCreate(HttpContext context, IntegrationCreatePayload payload, string trace) => DefaultResponse("IntegrationCreate", context, trace);
+    public override Task OnIntegrationDelete(HttpContext context, IntegrationDeletePayload payload, string trace) => DefaultResponse("IntegrationDelete", context, trace);
+    public override Task OnTest(HttpContext context, TestPayload payload, string trace) => DefaultResponse("Test", context, trace);
+    public override Task OnVoteCreate(HttpContext context, VoteCreatePayload payload, string trace) => DefaultResponse("VoteCreate", context, trace);
+
+    private static async Task DefaultResponse(string name, HttpContext context, string trace)
+    {
+        if (!context.Response.HasStarted)
+        {
+            context.Response.StatusCode = 200;
+
+            await context.Response.WriteAsync($"{name},{trace}");
+        }
+    }
+}

Topgg.Sdk.Webhooks/Tests/Mock.cs

@@ -0,0 +1,32 @@
+using System;
+using System.IO;
+using System.Linq;
+using System.Security.Cryptography;
+using System.Text;
+
+namespace Topgg.Sdk.Webhooks.Tests;
+
+internal class Mock
+{
+    internal static readonly string Secret = "testsecret1234";
+
+    internal static readonly string Prefix = "Topgg.Sdk.Webhooks.Tests.Mocks.";
+
+    internal static string[] Names = [.. typeof(Mock).Assembly.GetManifestResourceNames().Where(name => name.StartsWith(Prefix)).Select(name => name[Prefix.Length..(name.Length - 5)])];
+
+    internal static string ReadJson(string name)
+    {
+        using var stream = typeof(Mock).Assembly.GetManifestResourceStream($"{Prefix}{name}.json");
+        using var reader = new StreamReader(stream);
+
+        return reader.ReadToEnd();
+    }
+
+    internal static string Signature(string body)
+    {
+        var timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
+        var hash = Convert.ToHexString(HMACSHA256.HashData(Encoding.UTF8.GetBytes(Secret), Encoding.UTF8.GetBytes($"{timestamp}.{body}"))).ToLowerInvariant();
+
+        return $"t={timestamp},v1={hash}";
+    }
+}

Topgg.Sdk.Webhooks/Tests/Mocks/IntegrationCreate.json

@@ -0,0 +1,19 @@
+{
+  "type": "integration.create",
+  "data": {
+    "connection_id": "112402021105124",
+    "webhook_secret": "whs_abcd",
+    "project": {
+      "id": "1230954036934033243",
+      "platform": "discord",
+      "platform_id": "3949456393249234923",
+      "type": "bot"
+    },
+    "user": {
+      "id": "3949456393249234923",
+      "platform_id": "3949456393249234923",
+      "name": "username",
+      "avatar_url": "<avatar url>"
+    }
+  }
+}

Topgg.Sdk.Webhooks/Tests/Mocks/IntegrationDelete.json

@@ -0,0 +1,6 @@
+{
+  "type": "integration.delete",
+  "data": {
+    "connection_id": "112402021105124"
+  }
+}

Topgg.Sdk.Webhooks/Tests/Mocks/Test.json

@@ -0,0 +1,17 @@
+{
+  "type": "webhook.test",
+  "data": {
+    "user": {
+      "id": "160105994217586689",
+      "platform_id": "160105994217586689",
+      "name": "username",
+      "avatar_url": "<avatar url>"
+    },
+    "project": {
+      "id": "803190510032756736",
+      "type": "bot",
+      "platform": "discord",
+      "platform_id": "160105994217586689"
+    }
+  }
+}

Topgg.Sdk.Webhooks/Tests/Mocks/VoteCreate.json

@@ -0,0 +1,21 @@
+{
+  "type": "vote.create",
+  "data": {
+    "id": "808499215864008704",
+    "weight": 1,
+    "created_at": "2026-02-09T00:47:14.2510149+00:00",
+    "expires_at": "2026-02-09T12:47:14.2510149+00:00",
+    "project": {
+      "id": "803190510032756736",
+      "type": "bot",
+      "platform": "discord",
+      "platform_id": "160105994217586689"
+    },
+    "user": {
+      "id": "160105994217586689",
+      "platform_id": "160105994217586689",
+      "name": "username",
+      "avatar_url": "<avatar url>"
+    }
+  }
+}

Topgg.Sdk.Webhooks/Tests/Tests.cs

@@ -0,0 +1,59 @@
+using System.Collections.Generic;
+using System.Linq;
+using System.Net;
+using System.Net.Http;
+using System.Text;
+using System.Threading.Tasks;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.TestHost;
+using Microsoft.Extensions.DependencyInjection;
+using Xunit;
+
+namespace Topgg.Sdk.Webhooks.Tests;
+
+public class Tests
+{
+    public static IEnumerable<TheoryDataRow<string>> Payloads => Mock.Names.Select(payload => new TheoryDataRow<string>(payload));
+
+    private static readonly string Trace = "trace";
+    private readonly HttpClient Http;
+
+    public Tests()
+    {
+        var server = new TestServer(new WebHostBuilder().ConfigureServices(services =>
+        {
+            services.AddRouting();
+        }).Configure(app =>
+        {
+            app.UseRouting();
+            app.UseEndpoints(builder =>
+                {
+                    var webhooks = new CustomWebhooks();
+
+                    builder.MapPost("/webhook", webhooks.Handler);
+                });
+        }));
+
+        Http = server.CreateClient();
+    }
+
+    [Theory]
+    [MemberData(nameof(Payloads))]
+    public async Task Test(string payload)
+    {
+        var body = Mock.ReadJson(payload);
+
+        var response = await Http.SendAsync(new HttpRequestMessage(HttpMethod.Post, "/webhook")
+        {
+            Content = new StringContent(body, Encoding.UTF8, "application/json"),
+            Headers = {
+                    {"x-topgg-signature", Mock.Signature(body)},
+                    {"x-topgg-trace", Trace}
+                }
+        }, TestContext.Current.CancellationToken);
+
+        Assert.StrictEqual(HttpStatusCode.OK, response.StatusCode);
+        Assert.Equal($"{payload},{Trace}", await response.Content.ReadAsStringAsync(TestContext.Current.CancellationToken));
+    }
+}