Skip to main content
The notifications API lets you register HTTPS endpoints that receive real-time payloads when bot events occur (moderation actions, health alerts, config changes, etc.). Secrets are write-only — they are never returned in GET responses. Base path: /api/v1/guilds/:guildId/notifications Authentication: API key or JWT Bearer token required. Admin permission required. Limit: Maximum 20 webhook endpoints per guild.

​
Webhook events

The following event types can be subscribed to:
EventDescription
bot.disconnectedDiscord gateway disconnection
bot.reconnectedSuccessful reconnection
bot.errorUnhandled bot error
moderation.actionWarning, ban, or kick issued
health.degradedMemory >80% or event loop lag >100ms
config.changedConfig updated via dashboard
member.flaggedAI flagged a member’s message

​
GET /guilds/:guildId/notifications/webhooks

Returns all configured outbound webhook endpoints. Secrets are never included in the response. A hasSecret boolean indicates whether a signing secret is configured.

​
Path parameters

​
guildId
string
required
The Discord guild ID.

​
Response

An array of webhook endpoint objects.
​
id
string
UUID of the endpoint.
​
url
string
The HTTPS delivery URL.
​
events
array
List of subscribed event type strings.
​
enabled
boolean
Whether the endpoint is active.
​
hasSecret
boolean
true if an HMAC signing secret is configured. The secret itself is never returned.

​
Example

curl -H "x-api-secret: YOUR_SECRET" \
  "https://volvox.bot/api/v1/guilds/987654321/notifications/webhooks"

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "url": "https://example.com/hooks/volvox",
    "events": ["moderation.action", "config.changed"],
    "enabled": true,
    "hasSecret": true
  }
]

​
POST /guilds/:guildId/notifications/webhooks

Registers a new outbound webhook endpoint.

​
Path parameters

​
guildId
string
required
The Discord guild ID.

​
Request body

​
url
string
required
HTTPS delivery URL. Must start with https://. Private IP addresses and localhost are rejected (SSRF protection).
​
events
array
required
Non-empty array of event type strings to subscribe to. See event types table above.
​
secret
string
Optional HMAC-SHA256 signing secret. When set, each delivery includes an X-Webhook-Signature header you can use to verify authenticity.
​
enabled
boolean
default:"true"
Whether the endpoint is active immediately.

​
Response

Returns the created endpoint object (secret masked with hasSecret). HTTP 201 on success.

​
Example

curl -X POST \
  -H "x-api-secret: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/volvox",
    "events": ["moderation.action", "config.changed"],
    "secret": "my-hmac-secret",
    "enabled": true
  }' \
  "https://volvox.bot/api/v1/guilds/987654321/notifications/webhooks"

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://example.com/hooks/volvox",
  "events": ["moderation.action", "config.changed"],
  "enabled": true,
  "hasSecret": true
}

​
Error responses

StatusCause
400Missing or invalid url; url is not HTTPS; SSRF-blocked URL; invalid event types; events is empty; already at 20 endpoint limit
401Missing authentication

​
DELETE /guilds/:guildId/notifications/webhooks/:endpointId

Removes a webhook endpoint by its ID.

​
Path parameters

​
guildId
string
required
The Discord guild ID.
​
endpointId
string
required
UUID of the endpoint to remove.

​
Response

HTTP 204 No Content on success.

​
Example

curl -X DELETE \
  -H "x-api-secret: YOUR_SECRET" \
  "https://volvox.bot/api/v1/guilds/987654321/notifications/webhooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
POST /guilds/:guildId/notifications/webhooks/:endpointId/test

Sends a test event payload to a webhook endpoint and returns the delivery result.

​
Path parameters

​
guildId
string
required
The Discord guild ID.
​
endpointId
string
required
UUID of the endpoint to test.

​
Response

​
ok
boolean
Whether the delivery was successful (HTTP 2xx).
​
status
integer
HTTP status code returned by the endpoint.
​
body
string
First 500 characters of the response body.

​
Example

curl -X POST \
  -H "x-api-secret: YOUR_SECRET" \
  "https://volvox.bot/api/v1/guilds/987654321/notifications/webhooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/test"

{ "ok": true, "status": 200, "body": "ok" }

​
GET /guilds/:guildId/notifications/deliveries

Returns recent webhook delivery log entries for the guild, newest first.

​
Path parameters

​
guildId
string
required
The Discord guild ID.

​
Query parameters

​
limit
integer
default:"50"
Maximum entries to return. Maximum 100.

​
Example

curl -H "x-api-secret: YOUR_SECRET" \
  "https://volvox.bot/api/v1/guilds/987654321/notifications/deliveries?limit=10"

[
  {
    "endpointId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "event": "moderation.action",
    "status": 200,
    "ok": true,
    "deliveredAt": "2026-03-21T10:30:00.000Z"
  }
]

Build docs developers (and LLMs) love

Get started for freeTalk to us