Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 37 ยท Webhooks and Hosting

Discord Interactions Endpoint and Ed25519 Signatures

Build a Discord interactions HTTP endpoint in Node.js: verify Ed25519 request signatures with node:crypto, answer PING, respond to slash commands and defer slow work.

Discord can deliver slash commands, buttons, select menus and modals to a URL of your choice instead of over the gateway WebSocket. That makes a very light bot: a single HTTPS function, no always-on connection. The price is one strict requirement. Every request is signed with Ed25519, and your endpoint must verify the signature and reject anything that fails. Discord even tests this by sending you deliberately bad signatures when you save the URL.

Everything here uses only node:crypto and node:http. We generate our own key pair to act as "Discord", because the real public key and the real application cannot be used on this site. The verification code is identical to what runs in production.

What Discord sends

Each request is a POST with a JSON body and two headers:

  • X-Signature-Timestamp: a timestamp string.
  • X-Signature-Ed25519: the signature in hex.

The signed message is the timestamp concatenated with the raw body, byte for byte. This is the first trap: you must verify against the raw request text, not against JSON.stringify(JSON.parse(body)), because re-serializing can change whitespace and key order and the signature will no longer match.

Your public key is shown on your application's page in the Developer Portal as 64 hex characters (32 bytes).

Verifying with node:crypto

Node wants the key in a standard container (SPKI DER). An Ed25519 raw public key becomes valid DER by putting a fixed 12-byte prefix in front of it.

Node.js Sign and verify like Discord does

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The function returns a plain boolean and never throws on bad input; the regex check makes sure a malformed header cannot crash the process.

The full endpoint

Interaction types you must handle first:

type Meaning Your response
1 PING (also used to verify your URL) { "type": 1 } (PONG)
2 Application command (slash command) usually { "type": 4, "data": { "content": "..." } }
3 Message component (button, select) update the message or send a reply
5 Modal submit reply with a message

Response types: 4 sends a message, 5 defers (shows "thinking..." and gives you 15 minutes to follow up), 6 acknowledges a component without changing the message, 7 updates the message the component was on.

Node.js A signed interactions endpoint

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Note three details:

  1. The 401 on a bad signature is mandatory. Discord will refuse to save your endpoint URL if you answer a fake request with 200.
  2. The freshness check (MAX_AGE_SECONDS) is a defense you add on top. A captured valid request cannot be replayed an hour later. Discord's own documentation does not require it, but it costs nothing.
  3. flags: 64 makes a reply ephemeral: only the person who ran the command can see it. Use it for errors and private information.

Deferred responses and the 3 second rule

You have three seconds to answer an interaction. If a command takes longer (a database query, an HTTP call to another API), answer { "type": 5 } immediately. Discord shows "Bot is thinking...", and you then send the real answer with PATCH /webhooks/{application_id}/{interaction_token}/messages/@original within 15 minutes. The interaction token authorizes that call, so you do not need the bot token for it. Doing the slow work after returning the response is why bots with workers or queues matter on serverless platforms: the platform may freeze your function the moment you respond.

Registering the endpoint

In the Developer Portal, set "Interactions Endpoint URL" to your HTTPS address. Discord sends a signed PING and a bad-signature probe; saving succeeds only if you answer both correctly. Slash commands are registered separately with PUT /applications/{id}/commands, as covered in the commands chapter of this track.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What exactly does Discord sign?

    The signed message is timestamp + raw body, so both must be present and unchanged.
  2. 2. Why verify against the raw body text rather than parsed-then-stringified JSON?

    Signatures cover exact bytes; any change in formatting makes verification fail.
  3. 3. What must the endpoint return for a request with an invalid signature?

    Discord probes this when you save the URL. Accepting an unsigned request is a security hole.
  4. 4. Your slash command needs 8 seconds of work. What response type do you send first?

    You have 3 seconds to respond; a deferred response buys 15 minutes to follow up.

Summary

  • Discord signs each interaction with Ed25519 over timestamp + rawBody; verify before parsing and answer 401 on failure.
  • Convert the raw 32-byte public key to SPKI DER with a fixed prefix so node:crypto can use it.
  • Answer type 1 with type 1, commands with type 4 (message) or 5 (deferred).
  • Add a timestamp freshness check to block replays and use flags: 64 for private replies.
  • An interactions endpoint suits command-only bots and serverless hosting.

Next: Hosting and process management