Aller au contenu principal

Discord Webhook Setup Guide

This guide explains how to set up a Discord webhook for sharing duplicates to a Discord channel.

Prerequisites​

  • Access to Discord server settings (Admin or Manage Webhooks permission)
  • The channel where you want to receive duplicate notifications

Step 1: Create a Webhook in Discord​

  1. Open Discord and navigate to your server
  2. Go to Server Settings → Integrations → Webhooks
  3. Click New Webhook or Create Webhook
  4. Configure the webhook:
    • Name: Choose a name (e.g., "Aaperture Duplicates")
    • Channel: Select the channel where duplicates should be posted
    • Avatar: (Optional) Set a custom avatar
  5. Click Save Changes

Step 2: Copy Webhook URL​

  1. After creating the webhook, click Copy Webhook URL
  2. The URL format is: https://discord.com/api/webhooks/{WEBHOOK_ID}/{WEBHOOK_TOKEN}

Example:

https://discord.com/api/webhooks/123456789012345678/abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890

Step 3: Extract ID and Token​

From the webhook URL, extract:

  • WEBHOOK_ID: The first part after /webhooks/ (numeric, typically 18-19 digits)
  • WEBHOOK_TOKEN: The second part after the ID (alphanumeric string, typically 68+ characters)

Example:

  • URL: https://discord.com/api/webhooks/123456789012345678/abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890
  • ID: 123456789012345678
  • Token: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890

Step 4: Configure Environment Variables​

Add the following to your .env file:

# Discord Webhook Configuration
DISCORD_DUPLICATES_WEBHOOK_ID=123456789012345678
DISCORD_DUPLICATES_WEBHOOK_TOKEN=abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890

Important:

  • Do NOT include quotes around the values
  • Do NOT include the base URL (https://discord.com/api/webhooks/)
  • Do NOT include slashes or spaces
  • Copy the ID and token exactly as they appear in the webhook URL

Step 5: Restart Backend Server​

After updating the .env file, restart your backend server for the changes to take effect.

Troubleshooting​

Error 404: Not Found​

This error means the webhook doesn't exist or the ID/token is incorrect.

Solutions:

  1. Verify the webhook still exists in Discord:

    • Go to Server Settings → Integrations → Webhooks
    • Check if the webhook is listed
    • If it's missing, it may have been deleted

  2. Verify the ID and token are correct:

    • Copy the webhook URL again from Discord
    • Extract the ID and token carefully
    • Make sure there are no extra spaces or characters

  3. Check your .env file:

    • Ensure variables are named exactly: DISCORD_DUPLICATES_WEBHOOK_ID and DISCORD_DUPLICATES_WEBHOOK_TOKEN
    • Ensure there are no quotes around the values
    • Ensure there are no spaces before/after the values

  4. Create a new webhook if needed:

    • Delete the old webhook if it exists
    • Create a new webhook following Step 1
    • Update your .env file with the new credentials

Private Channels​

Good news: Webhooks work perfectly fine with private channels! The webhook doesn't need special permissions for private channels - it just needs to exist and have access to the channel.

Forum Channels​

If you're using a forum channel (thread-based channel), the webhook will automatically create a new thread for each duplicate shared. The thread title will be formatted as: {date} - {contact_name} (e.g., "13/11/2025 - John Doe").

Testing​

After configuration, try sharing a duplicate from the application. You should see:

  • A success message in the application
  • A new message (or thread) in your Discord channel
  • Logs in the backend console confirming the webhook was sent

Security Notes​

  • Never commit your .env file to version control
  • The webhook token is sensitive - treat it like a password
  • If a webhook token is compromised, delete the webhook and create a new one
  • Rotate webhook tokens periodically for security