Webhooks: Send signed server events to your own services

Outbound webhooks let you connect your server’s activity to anything you run. Register a URL and pick the events you care about, and whenever one of them fires, Percy sends a signed JSON payload to that URL. Use it to drive a status board, mirror events into another service, or trigger your own automations. Manage webhooks from Integrations → Webhooks on the dashboard. It requires the Manage Server permission.

Creating a webhook

Add the endpoint

Click Add Webhook, enter the Payload URL that should receive events (an https:// URL you control), and optionally a Label to identify it later.

Choose events

Tick the events this endpoint should receive. You can change the selection later.

Store the signing secret

On save, Percy shows a signing secret once. Copy it now — it is never shown again. You’ll use it to verify that deliveries genuinely came from Percy.

Event	Fires when
`member.join`	A member joins the server
`member.remove`	A member leaves the server
`member.ban`	A member is banned
`member.unban`	A member is unbanned
`role.create`	A role is created
`role.delete`	A role is deleted
`level.up`	A member reaches a new level
`moderation.case`	A moderation case is opened
`giveaway.ended`	A giveaway ends and winners are drawn

The delivery payload

Every delivery is a JSON envelope:

{
  "id": "b2f1c0e2-…",
  "event": "member.join",
  "guild_id": "123456789012345678",
  "sent_at": "2026-07-07T12:34:56.789012+00:00",
  "data": { }
}

id is unique per delivery — use it to de-duplicate retries.
guild_id is a string (so it survives JavaScript number limits).
data carries the event-specific fields.

Verifying the signature

Each request carries an X-Percy-Signature header of the form sha256=<hex>. It is the HMAC-SHA256 of the raw request body using your subscription’s secret. Recompute it and compare in constant time before trusting a delivery.

import hmac, hashlib

def verify(secret: str, raw_body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Sign against the exact bytes of the request body, not a re-serialised copy — re-encoding JSON can reorder keys or change spacing and break the signature.

Testing and monitoring

Test sends a sample ping payload to the endpoint and reports the result immediately, so you can confirm your receiver works.
Log shows recent delivery attempts — the event, whether it succeeded, the HTTP status, the number of tries, and any error.
The enable toggle pauses a subscription without deleting it.

Deliveries retry a few times on failure. A subscription that keeps failing is automatically disabled so a dead endpoint doesn’t pile up retries; re-enable it once your receiver is healthy again.

Getting Started

Moderation

Economy

Music

Community

Utility

Configuration

AI

Webhooks: Send signed server events to your own services

Creating a webhook

The delivery payload

Verifying the signature

Testing and monitoring

Next steps

Backup & Templates

Audit Log

​Creating a webhook

​Events you can subscribe to

​The delivery payload

​Verifying the signature

​Testing and monitoring

​Next steps

Backup & Templates

Audit Log

Creating a webhook

Events you can subscribe to

The delivery payload

Verifying the signature

Testing and monitoring

Next steps