Webhooks
Getting notified about votes, reviews and team changes in real time.
Webhooks let your server know the moment something happens to a bot, server or
team you own, instead of polling the API. Create one from the entity's settings
in your dashboard, or with
POST /{target_type}/{target_id}/webhooks.
The quickest way to receive them is one of our SDKs, which verify every signing method and hand you a typed event:
| Language | Verify with |
|---|---|
| JavaScript | createWebhookHandler(secret, onEvent) or verifyWebhook({ body, headers }, secret) |
| Python | verify_webhook(body, headers, secret) |
| Go | omniplex.WebhookHandler(secret, onEvent) or omniplex.VerifyWebhook(body, header, secret) |
| Rust | omniplex::verify_webhook(&body, &headers, secret) |
Creating a webhook
From the dashboard:
- Open your dashboard, find the bot or server, and click Webhooks. For a team, use the Webhooks section of the team's settings.
- Click New Webhook and give it a name and the URL to send to.
- For a Discord channel, paste the channel's Discord webhook URL and leave the secret blank. Omniplex posts a formatted message to the channel.
- For your own server, set a secret and choose HMAC signature (recommended) as the signing method.
- Use Test to send a test event, then check Delivery Logs to see what your server answered.
With the API, these are the fields:
| Field | Notes |
|---|---|
name | A label for the webhook. |
url | Where to send events. A Discord webhook URL also works: events are posted to that channel as embeds. |
secret | Used to sign or authenticate every delivery. Required, except for Discord webhook URLs. |
hmac_auth | Sign deliveries with HMAC-SHA256. Recommended for anything new. |
simple_auth | Send the secret itself instead of a signature. Can't be combined with hmac_auth. |
event_whitelist | Event types to send, such as ["NEW_VOTE"]. Empty sends every event. |
Signing methods
Every delivery has an X-Webhook-Protocol header naming the method, so you can
check you're verifying the right one.
hmac-sha256 (recommended)
Chosen with hmac_auth. The body is the event as plain JSON. The signature is
an HMAC-SHA256 of the raw body bytes, keyed with your secret, sent hex-encoded in
X-Webhook-Signature as sha256=<hex>. This is the same shape GitHub and
Stripe use.
import hashlib
import hmac
def verify(secret: str, raw_body: bytes, signature_header: str) -> bool:
expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature_header)const crypto = require("crypto");
function verify(secret, rawBody, signatureHeader) {
const expected =
"sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
return (
expected.length === signatureHeader.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader))
);
}Two things matter:
- Hash the raw body bytes, before any JSON parsing. Parsing and re-serialising won't reproduce the same bytes, so the signature won't match.
- Compare in constant time (
hmac.compare_digest,crypto.timingSafeEqualor equivalent), not with==. A plain comparison leaks timing information that can be used to guess the signature.
simple-auth (legacy)
Chosen with simple_auth. The body is plain JSON, and the secret itself is sent
in the Authorization header. Check it's an exact match. Only use this for
endpoints that can't check a signature at all.
splashtail (legacy default)
Used when neither option is set, and by webhooks created before hmac_auth
existed. The body is encrypted, so verifying it means decrypting it, not just
checking a signature. The SDKs handle this for you; to do it yourself:
- Read
X-Webhook-NonceandX-Webhook-Signature. - Check the signature:
hex(HMAC-SHA512(key = nonce, data = hex(HMAC-SHA512(key = secret, data = body)))). - The body is hex. Decode it. The first 12 bytes are the AES-GCM nonce and the rest is the ciphertext with its 16-byte tag.
- Decrypt with AES-256-GCM using the key
SHA-256(secret + nonce). The result is the event JSON.
For a new integration, switch the webhook to hmac_auth instead
(PATCH .../webhooks/{id} with "hmac_auth": true).
Responding
Reply with any 2xx once you've handled the event. Reply 401 or 403 when
verification fails. A 404 or 410 (or a deleted Discord channel webhook)
turns the webhook off, and the owner is told to fix the URL and save the webhook
again to turn it back on.
Other errors are recorded in Delivery Logs, and the owner is notified. A
webhook that fails 20 times in a row is paused until it's saved again. One
successful delivery resets the count, and one webhook failing never affects the
others. Requests time out after 30 seconds, and webhook URLs can't point at
localhost.
Omniplex sometimes sends a delivery signed with a throwaway secret, not your
real one, to check your endpoint rejects it. A correct verifier already does.
If your endpoint accepts one with a 2xx, the owner is warned that the webhook
isn't checking signatures, because anyone could send it fake events.
Events
Every event has the same envelope:
{
"type": "NEW_VOTE",
"data": { "votes": 12, "per_user": 2, "downvote": false, "auto": false },
"creator": {
"id": "510065483693817867",
"username": "sleepy",
"display_name": "Sleepy",
"avatar": "https://cdn.discordapp.com/embed/avatars/0.png",
"bot": false,
"status": "online",
"extra_data": {}
},
"targets": {
"bot": { "id": "1234567890123456789", "username": "Mellow", "bot": true }
},
"metadata": { "created_at": 1761700000, "test": false }
}| Field | Notes |
|---|---|
type | The event type, below. |
data | The event's own fields, below. |
creator | The user who caused the event, such as the voter. |
targets | The bot, server or team the event is about. |
metadata.created_at | When it happened, in seconds since the Unix epoch. |
metadata.test | true for test sends from the dashboard. |
type | data |
|---|---|
NEW_VOTE | votes (the new total), per_user (how many votes this vote counted as, 2 on a double-vote weekend), downvote, auto (cast by an Auto-vote subscription) |
NEW_REVIEW | review_id, content, stars, owner_review |
EDIT_REVIEW | review_id, stars and content as { "old": ..., "new": ... }, owner_review |
DELETE_REVIEW | review_id, content, stars, owner_review |
TEAM_EDIT | name, short, tags, extra_links and nsfw, each as { "old": ..., "new": ... } |
New event types may be added. Ignore types you don't recognise rather than failing; every SDK passes them through as an unknown event.