Test Discord Webhooks Locally

From a stuck handler to a live Discord delivery you can read and replay.

1. 1Start LocalCan and point it at your local server: localcan http 3000. It opens the tunnel and prints your .local domains plus a public HTTPS URL.
2. 2Grab your persistent URL, something like your-app-12.localcan.dev. It is saved to your project file and comes back identical after every restart, so you wire it up once.
3. 3Open your app in the Developer Portal, go to the General Information page (discord.com/developers/applications/select/information) and copy the Public Key. Your handler needs it before any of this succeeds. Paste your LocalCan URL plus your route into the Interactions Endpoint URL field, e.g. https://your-bot-12.localcan.dev/interactions, then click Save Changes. Discord’s docs render that label three ways (Interactions, Interaction, Interactive). It is the only URL field on the page. Webhook Events are separate, on the Webhooks page (discord.com/developers/applications/select/webhooks).
4. 4There is no test-event button: Save Changes is the test, and Discord fires the PING the moment you click it. If the save is refused, leave LocalCan capturing and click it again. The failed attempt is already in Inspect Traffic. Once the endpoint verifies, run a slash command to send a real APPLICATION_COMMAND through the same URL.
5. 5Open Inspect Traffic in LocalCan. The delivery lands with full headers and body. Expand it, fix your handler, and hit Replay to send the exact same request again. No new test event needed.

Discord saysValidation errors: interactions_endpoint_url: The specified interactions endpoint url could not be verified.

Header

X-Signature-Ed25519, alongside X-Signature-Timestamp

Algorithm

Ed25519 public-key signature, hex-encoded, not an HMAC

What's signed

Discord signs the X-Signature-Timestamp header value immediately followed by the exact bytes of the request body, with no separator between them. You verify that message against the X-Signature-Ed25519 value using your app’s public key. Both the signature and the key travel as hex. Because the raw body is part of the signed message, middleware that parses the JSON and hands your verifier a re-serialised object breaks the check while the payload still looks correct.

Secret

There is no shared secret. The Public Key on your app’s General Information page (discord.com/developers/applications/select/information) is public by design and only ever verifies.

import express from 'express'
import crypto from 'crypto'

// The Public Key from General Information is a raw 32-byte Ed25519 key in hex.
// Node wants a KeyObject, so wrap it in the fixed DER/SPKI prefix once at boot.
const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex')
const publicKey = crypto.createPublicKey({
  key: Buffer.concat([ED25519_SPKI_PREFIX, Buffer.from(process.env.DISCORD_PUBLIC_KEY, 'hex')]),
  format: 'der',
  type: 'spki',
})

const app = express()

// RAW body: the signature covers the exact bytes, so no JSON parser first.
app.post('/interactions', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.get('X-Signature-Ed25519')
  const timestamp = req.get('X-Signature-Timestamp')
  if (!signature || !timestamp) return res.status(401).send('missing signature headers')

  // Signed message is timestamp + raw body, concatenated with no separator.
  const message = Buffer.concat([Buffer.from(timestamp, 'utf8'), req.body])
  const ok = crypto.verify(null, message, publicKey, Buffer.from(signature, 'hex'))

  // 401 is mandatory: Discord sends invalid signatures as a routine security
  // check and removes the endpoint of any app that answers one with a 200.
  if (!ok) return res.status(401).send('invalid request signature')

  const interaction = JSON.parse(req.body)

  // PING (type 1): the check that must pass before the URL can be saved.
  if (interaction.type === 1) return res.json({ type: 1 })

  // Anything else: answer inside 3 seconds or the token is invalidated.
  res.json({ type: 4, data: { content: 'hello from localhost' } })
})

app.listen(3000)

A replayed capture still verifies, and it does not expire: Discord documents no timestamp tolerance for the Ed25519 check, so a PING captured this morning verifies this afternoon. One thing does expire: a replayed APPLICATION_COMMAND passes verification, but its interaction token was invalidated three seconds after the original arrived, so followup calls to Discord’s API with it fail. Replay exercises your handler, it does not produce a reply in Discord.