Pre-flight Discord Auditor

Validates and audits Discord webhook configurations before commands execute, ensuring notifications will be delivered successfully.

When to Use This Hook

Attach this hook when you need to:

• Verify Discord webhook URLs are valid and reachable before critical operations that depend on notification delivery
• Audit webhook permissions and channel configurations to catch misconfigurations before they cause silent notification failures
• Log all outgoing Discord notification attempts for compliance tracking and delivery confirmation

Consider alternatives when:

• Your Discord webhook is stable and well-tested and you do not need pre-flight validation overhead on every command
• You prefer post-hoc notification verification through Discord audit logs rather than pre-flight checks

Quick Start

Configuration

Copy
name: pre-flight-discord-auditor
type: hook
trigger: PreToolUse
category: automation

Example Trigger

Copy
git push origin main
# Hook fires before push executes:
# Pre-flight: Auditing Discord webhook configuration...

Example Output

Pre-flight Discord Audit:
Webhook URL: Configured (DISCORD_WEBHOOK_URL set)
Endpoint Test: 200 OK (response in 142ms)
Channel: #deployments (ID: 1234567890)
Guild: My Team Server
Rate Limit: 27/30 remaining
Webhook Owner: Claude Bot
Audit Log: Entry recorded at 2026-03-15T14:23:07Z
Status: READY - notifications will be delivered

Core Concepts

Pre-flight Audit Overview

Aspect	Details
Trigger Point	PreToolUse before Bash commands matching critical operation patterns
Validation Steps	URL format check, HTTP connectivity test, rate limit inspection
Audit Logging	Records each validation attempt with timestamp and result
Failure Mode	Warns but does not block command execution if webhook is unreachable
Cache Duration	Successful validation cached for 5 minutes to reduce API calls
API Method	HEAD request to webhook URL to verify availability without posting

Audit Workflow

PreToolUse Triggered
    |
    v
[Match critical command pattern?]
    |          |
   No         Yes
    |          |
 [Skip]       v
         [Check DISCORD_WEBHOOK_URL set?]
              |          |
             No         Yes
              |          |
           [Warn]       v
                   [Cache valid? (< 5 min)]
                        |          |
                       Yes        No
                        |          |
                     [Skip]       v
                             [HEAD request to webhook URL]
                                  |
                            +-----+-----+
                            |           |
                         200 OK      Error
                            |           |
                         [Log OK]    [Log failure + warn]
                            |           |
                            v           v
                        [Continue command execution]

Configuration

Parameter	Type	Default	Description
DISCORD_WEBHOOK_URL	string	(required)	Discord webhook URL to validate before critical operations
command_patterns	string	push|deploy|release	Regex pattern for commands that trigger pre-flight validation
cache_ttl	integer	300	Seconds to cache a successful validation before re-checking
audit_log_path	string	.claude/discord-audit.log	File path for the validation audit log
block_on_failure	boolean	false	Whether to block command execution when webhook validation fails

Best Practices

1. Enable blocking only for critical deployments - Set block_on_failure to true only for production deployment commands where missing a failure notification is unacceptable. For regular development commands, the default warn-only mode prevents the auditor from becoming a workflow bottleneck.

2. Review audit logs for delivery patterns - The audit log reveals patterns in webhook availability. If you notice recurring failures at specific times, it may indicate Discord API maintenance windows or rate limiting during peak team activity hours.

3. Use cache TTL to balance responsiveness and overhead - The default 5-minute cache prevents redundant API calls during rapid development. Reduce the TTL for high-stakes workflows where you need guaranteed fresh validation, or increase it for low-risk development sessions.

4. Set up a fallback webhook for redundancy - Configure a secondary webhook URL pointing to a different Discord channel or server. If the primary webhook fails validation, the auditor can automatically switch to the fallback to ensure notifications are never silently lost.

5. Coordinate audit timing with rate limits - Discord webhooks have a rate limit of approximately 30 requests per minute. The HEAD request for validation counts against this limit. Schedule audits strategically to avoid consuming rate limit capacity needed for actual notifications.

Common Issues

1. Audit passes but notifications still fail - The HEAD request validates webhook availability but does not test the full POST payload. If notification payloads contain malformed JSON or exceed Discord embed limits, they will fail despite passing the pre-flight audit. Test with a sample POST to verify end-to-end delivery.

2. Cache causes stale validation results - If a webhook is deleted or the channel is removed between cache refreshes, the auditor reports a valid status from cache. Reduce the cache_ttl for critical workflows or implement a cache invalidation mechanism tied to webhook configuration changes.

3. Rate limit warnings during busy sessions - Frequent pre-flight checks during rapid development sessions can trigger rate limit warnings. If you see rate limit alerts, increase the cache_ttl or narrow the command_patterns to trigger audits only on deployment-related commands.