Top.gg Webhook handler for Plug-based HTTP servers.

This module provides webhook handling functionality for receiving vote notifications from Top.gg, compatible with Phoenix and other Plug-based HTTP servers.

Examples

Using the Functional Listener (Recommended)

# In a Phoenix router:
defmodule MyAppWeb.Router do
  use MyAppWeb, :router

  # Create the webhook handler
  webhook_handler = TopggEx.Webhook.listener(fn payload, conn ->
    case payload do
      %{"user" => user_id, "type" => "upvote", "bot" => bot_id} ->
        # Handle the vote
        MyApp.handle_user_vote(user_id, bot_id)
        IO.puts("User #{user_id} voted for bot #{bot_id}!")

      %{"user" => user_id, "type" => "test"} ->
        # Handle test webhook
        IO.puts("Test webhook from user #{user_id}")
    end

    # Response is handled automatically by the listener
  end, authorization: "your_webhook_auth_token")

  scope "/webhooks" do
    pipe_through :api
    post "/topgg", webhook_handler
  end
end

# In a standalone Plug application:
defmodule MyApp.Router do
  use Plug.Router

  plug :match
  plug :dispatch

  # Option 1: Use the convenient handle_webhook function (Recommended)
  post "/webhook" do
    TopggEx.Webhook.handle_webhook(conn, "your_webhook_auth_token", fn payload ->
      case payload do
        %{"user" => user_id, "type" => "upvote", "bot" => bot_id} ->
          MyApp.handle_user_vote(user_id, bot_id)
          IO.puts("User #{user_id} voted for bot #{bot_id}!")

        %{"user" => user_id, "type" => "test"} ->
          IO.puts("Test webhook from user #{user_id}")
      end
    end)
  end

  # Option 2: Define a helper function for reusability
  defp handle_webhook(conn) do
    case TopggEx.Webhook.verify_and_parse(conn, "your_webhook_auth_token") do
      {:ok, payload} ->
        case payload do
          %{"user" => user_id, "type" => "upvote", "bot" => bot_id} ->
            MyApp.handle_user_vote(user_id, bot_id)
            IO.puts("User #{user_id} voted for bot #{bot_id}!")

          %{"user" => user_id, "type" => "test"} ->
            IO.puts("Test webhook from user #{user_id}")
        end
        send_resp(conn, 204, "")

      {:error, reason} ->
        send_resp(conn, 400, "Error: #{inspect(reason)}")
    end
  end

  post "/webhook-custom" do
    handle_webhook(conn)
  end

  match _ do
    send_resp(conn, 404, "Not found")
  end
end

Using as Plug Middleware (Alternative)

# In your Phoenix router:
defmodule MyAppWeb.Router do
  use MyAppWeb, :router

  pipeline :webhook do
    plug :accepts, ["json"]
    plug TopggEx.Webhook, authorization: "your_webhook_auth_token"
  end

  scope "/webhooks" do
    pipe_through :webhook
    post "/topgg", YourController, :handle_vote
  end
end

# In your controller:
defmodule YourController do
  use MyAppWeb, :controller

  def handle_vote(conn, _params) do
    case conn.assigns.topgg_payload do
      %{"user" => user_id, "type" => "upvote"} ->
        # Handle the vote
        IO.puts("User #{user_id} voted!")
        send_resp(conn, 204, "")

      %{"user" => user_id, "type" => "test"} ->
        # Handle test webhook
        IO.puts("Test webhook from user #{user_id}")
        send_resp(conn, 204, "")

      _ ->
        send_resp(conn, 400, "Invalid payload")
    end
  end
end

Functional API

You can also use the functional API for more control:

# Verify and parse a webhook request
case TopggEx.Webhook.verify_and_parse(conn, "your_auth_token") do
  {:ok, payload} ->
    # Handle the vote payload
    IO.inspect(payload)

  {:error, :unauthorized} ->
    # Handle unauthorized request
    send_resp(conn, 403, Jason.encode!(%{error: "Unauthorized"}))

  {:error, :invalid_body} ->
    # Handle malformed request
    send_resp(conn, 400, Jason.encode!(%{error: "Invalid body"}))
end

Webhook Data Schema

The webhook payload typically contains:

• user - The ID of the user who voted
• type - The type of vote ("upvote" or "test")
• bot - The ID of the bot that was voted for
• isWeekend - Whether the vote was cast on a weekend (counts as 2 votes)
• query - Query parameters from the vote page (if any)

Links

• Top.gg Webhook Documentation
• Top.gg Webhook Schema