Integrations

Webhook integrations allow developers to build approved, installable integrations on Top.gg. Integrations use the same Webhooks system but operate as a bi-directional RPC-like flow during setup, enabling users to connect your service with a single click.

Integrations require approval from Top.gg before they can be listed.

How It Works

When a user connects your integration, Top.gg initiates a handshake with your integration config URL. Your service responds with its webhook configuration, and the connection is established automatically.

Handshake

The integration connection follows a four-step handshake:

1. User Initiates Connection

The user presses the Connect button on your integration page within Top.gg.

2. Top.gg Sends integration.create

Top.gg sends a POST request to your integration config URL with the integration.create event.

integration.create Payload

Field	Type	Description
type	string	Always "integration.create".
data.connection_id	string	Unique identifier for this connection.
data.webhook_secret	string	The secret used to verify future webhook deliveries.
data.project.id	snowflake	The Top.gg project ID.
data.project.platform	string	The platform the project belongs to (e.g. "discord").
data.project.platform_id	snowflake	The platform-specific ID for the project.
data.project.type	string	The project type (e.g. "bot").
data.user.id	snowflake	The Top.gg user ID of the adder.
data.user.platform_id	snowflake	The platform-specific ID of the adder.
data.user.name	string	The username of the user who added your integration.
data.user.avatar_url	string	The icon url of the user who added your integration.

Example Payload

{
  "type": "integration.create",
  "data": {
    "connection_id": "112402021105124",
    "webhook_secret": "whs_abcd",
    "project": {
      "id": "1230954036934033243",
      "platform": "discord",
      "platform_id": "3949456393249234923",
      "type": "bot"
    },
    "user": {
      "id": "top.gg id",
      "platform_id": "discord id",
      "name": "username",
      "avatar_url": "<avatar url>"
    }
  }
}

3. Respond With Configuration

Defer the request, store the connection_id and webhook_secret, then immediately respond with your webhook configuration.

Response Body

Field	Type	Description
webhook_url	string	The URL where Top.gg should deliver webhook events for this connection.
routes	string[]	An array of webhook scopes to subscribe to.

Example Response

{
  "webhook_url": "https://your.bot/webhooks/xyz",
  "routes": [
    "vote.create"
  ]
}

4. Connected

The integration is now active. Top.gg will deliver webhook events matching the subscribed routes to the provided webhook_url, signed with the webhook_secret from the handshake.

Disconnecting an Integration

Whenever the user deleted a managed webhook, a integration.delete event is pushed to the integration.

Payload

Field	Type	Description
type	string	Always "integration.delete".
data.connection_id	string	Unique identifier for this connection.

Example Json

{
  "type": "integration.delete",
  "data": {
    "connection_id": "112402021105124",
  }
}