Skip to content

Webhook events

The gateway tells your bot when it joins a server, but not when someone installs it to their account (user installs). Discord reports those, and entitlement changes, through webhook events sent to a URL you choose. Shardlens receives them on the collector, not in your bot.

  1. Give the collector your public key

    Copy General Information → Public Key from the Developer Portal into .env as DISCORD_PUBLIC_KEY, then restart the collector.

  2. Point Discord at the collector

    Under Webhooks, set the endpoint URL to https://stats.example.com/v1/discord/events and save. Discord sends a signed test request; the collector verifies it and answers.

  3. Turn on events and subscribe to:

    • APPLICATION_AUTHORIZED and APPLICATION_DEAUTHORIZED (installs and removals, for servers and users)
    • ENTITLEMENT_CREATE, ENTITLEMENT_UPDATE and ENTITLEMENT_DELETE (premium)

User installs then appear on the Growth page, and entitlement changes on the Premium page. For an estimated monthly revenue there, enter each subscription SKU’s monthly price under Settings → SKU prices: Discord sends SKU IDs, not amounts.

  • Every request is checked against your public key (Ed25519). Bad signatures and timestamps older than 5 minutes get 401.
  • The collector answers 204 before doing any work, so Discord’s response deadline is never at risk. Retried deliveries are stored once.
  • The installing user’s ID is hashed with the current salt, exactly like the SDK does, so the same person has the same hash in both places within a salt period. The raw ID is not stored (in audit mode it is stored encrypted).