discord-webhooks

Discord Webhooks

When to Use This Skill

• Setting up Discord webhook event handlers (outgoing webhooks)
• Verifying Discord Ed25519 signatures with X-Signature-Ed25519 and X-Signature-Timestamp
• Handling the PING (type 0) endpoint validation request
• Handling events like APPLICATION_AUTHORIZED, APPLICATION_DEAUTHORIZED, ENTITLEMENT_CREATE, LOBBY_MESSAGE_CREATE, GAME_DIRECT_MESSAGE_CREATE, QUEST_USER_ENROLLMENT
• Debugging "invalid request signature" errors when registering your webhook endpoint

Note: This skill covers outgoing webhooks (Discord → your server) — the same Ed25519 signing scheme is shared with Interactions endpoints. Incoming webhooks (your server → Discord channel via webhook URL) are not signed and not covered here.

Essential Code (USE THIS)

Discord uses Ed25519 asymmetric signatures (not HMAC). The signed content is the raw concatenation X-Signature-Timestamp + raw_body. Verification uses your application's public key (hex-encoded), available in the Discord Developer Portal.

Express Webhook Handler (Node.js)

Use the official-style discord-interactions helper (built on tweetnacl).

const express = require('express');
const { verifyKey } = require('discord-interactions');

const app = express();

// CRITICAL: Use express.raw() - verification needs raw body bytes
// Note: discord-interactions v4 returns a Promise from verifyKey — await it.
app.post('/webhooks/discord',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['x-signature-ed25519'];
    const timestamp = req.headers['x-signature-timestamp'];
    const publicKey = process.env.DISCORD_PUBLIC_KEY;

    if (!signature || !timestamp) {
      return res.status(401).send('Missing signature headers');
    }

    const isValid = await verifyKey(req.body, signature, timestamp, publicKey);
    if (!isValid) {
      return res.status(401).send('Invalid request signature');
    }

    const payload = JSON.parse(req.body.toString());

    // type: 0 = PING (endpoint validation). Reply 204 empty body.
    if (payload.type === 0) {
      return res.status(204).send();
    }

    // type: 1 = event payload
    if (payload.type === 1) {
      const event = payload.event;
      switch (event.type) {
        case 'APPLICATION_AUTHORIZED':
          console.log('App authorized for user:', event.data.user?.id);
          break;
        case 'APPLICATION_DEAUTHORIZED':
          console.log('App deauthorized for user:', event.data.user?.id);
          break;
        case 'ENTITLEMENT_CREATE':
          console.log('Entitlement created:', event.data.id);
          break;
        case 'LOBBY_MESSAGE_CREATE':
          console.log('Lobby message:', event.data.content);
          break;
        case 'GAME_DIRECT_MESSAGE_CREATE':
          console.log('Game DM:', event.data.content);
          break;
        default:
          console.log('Unhandled event type:', event.type);
      }
    }

    res.status(204).send();
  }
);