Submit Your Bot

Setting Up Webhooks for Bot Monitoring

Configure real-time alerts for bot uptime changes, review notifications, and health events directly to your Discord server or Slack workspace.

Overview

Webhook Basics

BotForge webhooks push event data to your endpoint the moment something changes — no polling required. Create webhooks from your dashboard at app.botforge.io → Developer → Webhooks and choose from three delivery targets: Discord incoming webhooks, Slack incoming webhooks, or raw HTTP POST endpoints you control.

Each webhook subscription is scoped to a single bot listing. You can attach up to five webhook endpoints per bot. BotForge delivers events with at-least-once semantics and retries failed deliveries for up to 24 hours with exponential backoff (initial delay 2 s, max delay 60 s).

Uptime Events

Receive bot.uptime.status_changed when a bot transitions between Online, Degraded, or Offline. Includes timestamp, previous status, and the probe region that detected the change (e.g., us-east-1, eu-west-2, ap-south-1).

Review Events

Receive bot.review.created when a user submits a star rating or comment. The payload carries the reviewer's public nickname, rating (1–5), review text, and a direct link to the review on BotForge.

Health Events

Receive bot.health.ping_slow when average response latency exceeds your configured threshold (default 500 ms). Also triggers bot.health.command_failure if the /ping or /status command returns a non-200 response for three consecutive checks within a 10-minute window.

Step-by-Step

Setup Guide

Follow these steps to create your first webhook endpoint and start receiving monitoring alerts.

1. Generate a Destination URL

For Discord: In your server settings, go to Integrations → Webhooks → New Webhook. Copy the URL — it will look like https://discord.com/api/webhooks/1048576/AbCdEfGhIjKlMnOpQrStUvWxYz. Assign the webhook a name like "BotForge Alerts" and optionally upload the BotForge icon.

For Slack: Open Slack → Settings & Administration → Manage apps → Incoming Webhooks. Activate it, select a channel (e.g., #bot-monitoring), and copy the generated URL starting with https://hooks.slack.com/services/T01ABC/B02DEF/xYz.

For custom HTTP: Provide any HTTPS endpoint that accepts POST requests with Content-Type: application/json. BotForge will send a X-BotForge-Signature header (HMAC-SHA256) so you can verify the request originated from BotForge.

2. Create the Webhook in BotForge

Navigate to app.botforge.io → Developer → Webhooks and click + New Webhook. Fill in the form:

Click Create Webhook. The new webhook appears in your list with a status of Active. BotForge immediately sends a bot.webhook.verified test event so you can confirm delivery.

3. Verify Delivery

Check your Discord channel, Slack channel, or HTTP logs for the test event. If you do not see it within 60 seconds, click the Resend Test Event button next to the webhook entry. For HTTP endpoints, BotForge also exposes a Delivery Log panel showing the last 50 requests, their status codes, and response times.

Reference

Payload Structure

Every webhook delivery is a JSON object wrapped in a standard envelope. Below are examples for each event type.

Envelope

All payloads share this outer structure:

{
  "id": "evt_9f8e7d6c5b4a3210",
  "type": "bot.uptime.status_changed",
  "timestamp": "2025-06-12T14:32:07Z",
  "bot": {
    "id": "bot_3c2b1a09",
    "name": "NitroGuard",
    "slug": "nitroguard"
  },
  "data": { ... }
}

Uptime Event Payload

{
  "id": "evt_9f8e7d6c5b4a3210",
  "type": "bot.uptime.status_changed",
  "timestamp": "2025-06-12T14:32:07Z",
  "bot": {
    "id": "bot_3c2b1a09",
    "name": "NitroGuard",
    "slug": "nitroguard"
  },
  "data": {
    "previous_status": "online",
    "current_status": "offline",
    "probe_region": "us-east-1",
    "downtime_duration_ms": 0,
    "last_check_url": "https://nitroguard.example.com/api/ping"
  }
}

Review Event Payload

{
  "id": "evt_a1b2c3d4e5f67890",
  "type": "bot.review.created",
  "timestamp": "2025-06-12T15:10:44Z",
  "bot": {
    "id": "bot_3c2b1a09",
    "name": "NitroGuard",
    "slug": "nitroguard"
  },
  "data": {
    "review_id": "rev_77889900",
    "reviewer": {
      "nickname": "ShadowPing42",
      "avatar_url": "https://cdn.botforge.io/avatars/shadowping42.png"
    },
    "rating": 4,
    "text": "Solid moderation bot. The auto-moderation rules are easy to configure, but I wish the welcome messages supported more embed formatting.",
    "review_url": "https://botforge.io/bots/nitroguard#rev_77889900"
  }
}

Health Event Payload

{
  "id": "evt_1122334455667788",
  "type": "bot.health.ping_slow",
  "timestamp": "2025-06-12T16:05:19Z",
  "bot": {
    "id": "bot_3c2b1a09",
    "name": "NitroGuard",
    "slug": "nitroguard"
  },
  "data": {
    "metric": "response_latency_ms",
    "value": 1247,
    "threshold": 500,
    "window_minutes": 10,
    "sample_count": 12,
    "probe_region": "eu-west-2"
  }
}
Support

Troubleshooting

If your webhooks are not delivering as expected, work through the checks below before opening a support ticket.

No Events Arriving

Confirm the webhook status is Active (not Paused or Failed). Verify the destination URL is publicly reachable — BotForge cannot deliver to localhost or private IP addresses. For Discord and Slack, ensure the webhook has not been revoked from the destination platform's side.

Signature Verification Fails

The X-BotForge-Signature header is an HMAC-SHA256 hex digest computed as HMAC_SHA256(body, secret). Make sure you are hashing the raw request body, not a parsed or URL-encoded version. BotForge sends the signature in the format sha256=<hex>.

Rate Limits & Retries

BotForge caps webhook deliveries at 100 events per minute per endpoint. If your endpoint returns a 429 or any 5xx status, BotForge retries with exponential backoff up to 10 times over 24 hours. After exhausting retries, the webhook status flips to Failed and you receive an email at the dashboard contact address. Fix the endpoint and click Reactivate.

Discord Formatting Issues

BotForge auto-formats Discord payloads using embeds. If your channel uses a webhook token that lacks the Send Messages permission, deliveries silently fail. Test by posting a manual message to the channel via the Discord web UI first. For Slack, ensure the channel is not archived.

Still stuck? Open a ticket at support.botforge.io with your webhook ID (visible in the URL as wh_ followed by a hex string) and a screenshot of the delivery log. Our team typically responds within 4 business hours.