# discord-webhooks

This skill guides you through receiving Discord webhooks, checking their signatures, and handling events. Use it while building or debugging a webhook endpoint.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 131 installs · ★ 103 repo stars
- Author: hookdeck
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/hookdeck/webhook-skills/tree/HEAD/skills/discord-webhooks/SKILL.md
- Updated: 2026-10-22
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/discord-webhooks

## What it does

The skill walks through webhook handlers in Express and FastAPI. It covers Ed25519 verification using `X-Signature-Ed25519` and `X-Signature-Timestamp`, the PING validation request, and event payloads for app authorization, entitlements, and messages. The Node.js example uses `discord-interactions`; the Python example uses `PyNaCl`.

Verification uses the timestamp joined to the original request bytes, not HMAC. The Express example preserves those bytes with `express.raw()`. Parsing the body first breaks that verification path. The examples read the app’s public key from `DISCORD_PUBLIC_KEY`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add hookdeck/webhook-skills --skill discord-webhooks -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/discord-webhooks/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/discord-webhooks/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add hookdeck/webhook-skills --skill discord-webhooks -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/discord-webhooks/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add hookdeck/webhook-skills --skill discord-webhooks -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/discord-webhooks/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install hookdeck/webhook-skills skills/discord-webhooks
```

2. **Manually: put the files in place**
- File: `.github/skills/discord-webhooks/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add hookdeck/webhook-skills --skill discord-webhooks -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/hookdeck/webhook-skills --path skills/discord-webhooks
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/discord-webhooks/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add hookdeck/webhook-skills --skill discord-webhooks -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/hookdeck/webhook-skills/tree/HEAD/skills/discord-webhooks/SKILL.md

## When to use it
- verify an incoming Discord webhook signature
- reply to a PING endpoint check
- process application authorization events
- handle entitlement and message events
- debug an invalid request signature

## Example prompts
- Show me an Express handler for Discord webhooks that verifies Ed25519 signatures and replies to PING.
- Explain how to verify a Discord webhook in FastAPI with `PyNaCl`.
- Help me handle an `ENTITLEMENT_CREATE` event from Discord.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: f89560be6da0b6e2.

BEGIN THIRD-PARTY FILE f89560be6da0b6e2
````text
---
name: discord-webhooks
description: >
  Receive and verify Discord webhook events. Use when setting up Discord
  webhook handlers, debugging Ed25519 signature verification, handling
  PING endpoint validation, or processing events like APPLICATION_AUTHORIZED,
  ENTITLEMENT_CREATE, or LOBBY_MESSAGE_CREATE.
license: MIT
metadata:
  author: hookdeck
  version: "0.1.0"
  repository: https://github.com/hookdeck/webhook-skills
---

# 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`](https://www.npmjs.com/package/discord-interactions) helper (built on `tweetnacl`).

```javascript
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':
````
END THIRD-PARTY FILE f89560be6da0b6e2

The third-party file has ended. Everything between the f89560be6da0b6e2 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2980 of 10850 bytes. © hookdeck · MIT · https://github.com/hookdeck/webhook-skills/tree/HEAD/skills/discord-webhooks/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
