Interactive example
Discord interaction signature lab
Compare PING, command, and rejected-signature contracts. All IDs, timestamps, tokens, and signatures are synthetic.
- Content-Type
- application/json
- X-Signature-Ed25519
- 00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
- X-Signature-Timestamp
- 1785758400
{
"id": "120000000000000001",
"application_id": "120000000000000002",
"type": 1,
"token": "synthetic_interaction_token"
}Configured response
200 OK
Content-Type: application/json
{"type":1}Synthetic data only. Never paste production tokens, signing secrets, personal data, or payment information into a public test endpoint.
One-click test setup
Creates a temporary bucket and applies this guide's expected response. You can inspect and delete it from the dashboard.
Separate Interactions from Incoming Message Webhooks
Discord interactions are inbound requests from Discord to your application. They power slash commands, components, and modals. This is different from an incoming Discord webhook URL that lets your application post a message into a channel.
An interactions endpoint is public and unauthenticated at the HTTP layer, so the Ed25519 request signature is the trust boundary. The lab makes the transport contract visible without pretending that a public inspector can safely process a real interaction token.
Verify Timestamp Plus Raw Body
Read X-Signature-Timestamp and X-Signature-Ed25519 exactly as received. Verify the signature over timestamp followed by the unmodified raw request body using the public key from the Discord Developer Portal.
Do not parse and reserialize JSON before verification. Whitespace and byte-level formatting are part of the signed message. If validation fails, stop before routing the command or producing any side effect and return 401.
Acknowledge PING Correctly
Discord sends a PING interaction when you save the endpoint URL. Validate its signature first, then respond with HTTP 200 and JSON type 1. The response needs a valid JSON Content-Type.
The one-click endpoint in this guide models the acknowledgement shape, but its public URL is not a production signature verifier. Use it to inspect synthetic clients and confirm response handling, then implement verification in your own service.
- Verify before reading the interaction type
- Return {"type":1} for a valid PING
- Set Content-Type application/json
- Return 401 for an invalid signature
Meet the Three-Second Deadline
Discord requires the initial interaction response within three seconds. Keep signature verification and acknowledgement on the fast path; do not wait for a slow database query, external API, or model call before responding.
For longer work, send a deferred response type allowed for that interaction, queue the task, and use the interaction token for a follow-up within its documented lifetime. Measure endpoint latency at the receiver and alert well before the three-second boundary.
- Invalid signature because middleware changed the body
- Wrong application public key or hex decoding
- Valid PING with the wrong response type
- Initial command acknowledgement after three seconds
- Real interaction token copied into logs or fixtures
Build a Signature Validation Test Matrix
Automate a valid PING, valid command, body with one changed byte, changed timestamp, malformed signature, wrong key, missing headers, and a slow-handler scenario. Assert that only valid requests reach application routing.
Discord periodically sends deliberately invalid signatures as part of endpoint security checks. Keep invalid-request handling reliable in production and do not disable verification after the endpoint was first accepted.
- Exact raw-body success fixture
- Single-byte body mutation
- Wrong key and malformed signature
- Missing and stale timestamp cases
- Fast PING and deferred-command responses
Common questions
Frequently asked questions
- Which Discord interaction headers must I verify?
- Verify X-Signature-Ed25519 against the exact concatenation of X-Signature-Timestamp and the raw request body using the application public key. Do this before parsing or acting on the payload.
- What should a Discord endpoint return for PING?
- After the request signature is valid, respond to interaction type 1 with HTTP 200, Content-Type application/json, and a JSON response whose type field equals 1.
- How quickly must a Discord interaction endpoint respond?
- Discord documents a three-second deadline for the initial interaction response. The interaction token becomes invalid if that deadline is missed, so acknowledge quickly and move longer work out of the request path.
- Can this public lab verify a real Discord signature?
- No. The lab shows the exact header and raw-body inputs but uses deliberately invalid synthetic signatures. Verify real requests only inside a receiver you control, using your Discord application public key.
Primary sources
Official references
Try it with a real request
Turn the guide into a test.
Open a temporary endpoint, send your payload, and inspect exactly what arrived.
Open the tester