Webhook Rewards

Webhook Rewards let you send HTTP requests when a reward runs (for example: Discord messages, website notifications, automation triggers, external logging, etc.).

This system is generic and not Discord-only. Discord is just the most common use case.

How it works

Webhook rewards are split into two parts:

Webhook Definitions (in Config.yml)
Defines where and how requests are sent
Webhook Reward Entries (in reward configs)
Defines what is sent and when

Rewards reference webhook definitions by ID.

Full Config.yml example (recommended)

Webhooks:
  Enabled: true
  Definitions:
    discord-staff:
      Enabled: true
      Url: "https://discord.com/api/webhooks/XXXX/XXXX"
      Method: POST
      ContentType: "application/json"
      TimeoutMs: 8000
      Headers:
        X-Server: "{SERVER}"
      HandleDiscordRateLimits: true
      Retry:
        Enabled: true
        MaxAttempts: 5
        BackoffMs: 1500
        MaxBackoffMs: 15000
      Signature:
        Enabled: false
        Algo: "HMAC_SHA256"
        Header: "X-Signature"
        Secret: "change-me"

Config option breakdown

`Webhooks.Enabled`

Master enable switch.
If false, no webhook requests are sent, even if rewards reference them.

`Definitions`

Holds named webhook endpoints.
Rewards reference these using:

webhook: "discord-staff"

`Definitions.<id>.Enabled`

Enables or disables a single webhook definition.

Useful for temporarily disabling one endpoint without editing rewards.

`Url`

Target endpoint URL.

Examples: - Discord webhook URL - Custom REST API - Automation tools (Zapier, Make, n8n, etc.)

Discord webhook tokens are automatically redacted in logs.

`Method`

HTTP method used for the request.

Supported values: - POST (default) - PUT - PATCH

`ContentType`

Sent as the Content-Type header.

Almost always:

application/json

`TimeoutMs`

Connect + read timeout in milliseconds.

Prevents webhook requests from hanging threads.

Default: 8000

`Headers`

Optional additional HTTP headers.

Values support placeholders
Useful for API keys, authorization, server identification

Example:

Headers:
  Authorization: "Bearer YOUR_TOKEN"
  X-Server: "{SERVER}"

`HandleDiscordRateLimits`

Discord-specific safety option.

If enabled and Discord responds with HTTP 429 containing retry_after: - VotingPlugin waits for the requested duration - Then retries automatically

Recommended: true for Discord webhooks.

`Retry`

Controls retry behavior for all webhook types.

Option	Description
`Enabled`	Enables retries
`MaxAttempts`	Total attempts (including first)
`BackoffMs`	Initial delay before retry
`MaxBackoffMs`	Maximum backoff cap

This protects external services and avoids message loss.

`Signature`

Optional request signing using HMAC.

When enabled: - VotingPlugin signs the raw request body - Signature is sent in the configured header

Field	Description
`Enabled`	Turns signing on/off
`Algo`	`HMAC_SHA256`
`Header`	Header name to send signature
`Secret`	Shared secret (supports placeholders)

Use this if you control the receiving API and want to verify authenticity.

Using webhooks in rewards

Webhook rewards are executed through an injected reward section.

Recommended format

WebhookReward:
  Webhooks:
    - webhook: "discord-staff"
      content:
        enabled: true
        message: "✅ {PLAYER} voted on {SERVICE_SITE}"

Why this format? - Works cleanly with AdvancedCore injected rewards - Keeps webhook data grouped and predictable

Discord embed example

WebhookReward:
  Webhooks:
    - webhook: "discord-staff"
      content:
        enabled: false
      embed:
        enabled: true
        title: "New Vote!"
        description: "{PLAYER} voted on {SERVICE_SITE}"
        color: "#2ecc71"
        footer:
          enabled: true
          message: "{TIMESTAMP}"

Raw JSON example (generic APIs)

WebhookReward:
  Webhooks:
    - webhook: "my-api"
      json: |
        {
          "event": "vote",
          "player": "{PLAYER}",
          "uuid": "{UUID}",
          "site": "{SERVICE_SITE}",
          "server": "{SERVER}"
        }

Use raw JSON when sending to: - Your own web services - Logging endpoints - Automation tools

Troubleshooting

Nothing sends

Check: - Webhooks.Enabled is true - The webhook definition exists and is enabled - The reward is actually running - The reward references a valid webhook ID

Discord messages missing

Common causes: - Deleted Discord channel - Invalid webhook URL - Rate limits with retries disabled - Invalid JSON (raw mode)

Summary

Webhooks are definition-based
Rewards reference webhooks by ID
Supports Discord, APIs, and automation services
Retry-safe, rate-limit-aware, and extensible

This system is designed to grow without breaking existing configurations.