Webhook Verification

To ensure that incoming requests are genuinely from Hytale-Servers.pro and have not been tampered with, all webhook POST requests include a cryptographic signature.

You should verify this signature before processing any kind of function when a vote has happened.

The Shared Secret

When you set up your webhook in our dashboard, you will be provided with a Webhook Secret.

Treat this like a password.
Never share it or commit it to a public repository.
Store it in an environment variable (e.g., WEBHOOK_SECRET).

Request Structure

We send a POST request to your provided URL with the following headers and body:

Header: X-Webhook-Signature - A hex-encoded HMAC-SHA256 signature of the request body.
Header: Content-Type: application/json
Body: A JSON string containing the vote details and a timestamp.

Example Payload:

{
  "hytale_username": "Player123",
  "timestamp": 1700000000000,
  "server_slug": "abcdefg",
  "vote_id": "abc123def456"
}

Verification Logic

To verify the request, you must:

Capture the raw, unparsed request body as a string.
Create an HMAC-SHA256 hash using your Secret and that raw body.
Compare your generated hash with the one provided in the X-Webhook-Signature header.

Security Best Practices

Use the Raw Body: Do not use req.body if your framework parses the body automatically. Re-stringifying an object can change spacing or key order, which will cause the signature to fail.
Timing Attacks: Use a constant-time comparison function (like Node's timingSafeEqual) to prevent attackers from guessing your signature character by character.
Timestamp Check: Always verify the timestamp in the payload. We recommend rejecting any request older than 5 minutes to prevent "replay attacks" (where a valid request is intercepted and re-sent multiple times).

Custom Voting Webhooks Documentation