Reward callbacks

The reward callback is the core vote→reward loop. When a player gives your server a heart, MMOLove sends a signed POST to your callback URL so you can grant an in-game reward — more votes, more rewards, more reasons to vote. This is the webhook the heart button on your listing fires.

This page is the overview + the authoritative payload and signing reference. For copy-paste handlers, the legacy GET mode, self-verification, and a full error table, follow the section pages below.

How it works

Set it up

Configure the callback on your server's dashboard under the Integration tab:

• Reward callback URL — a public https:// endpoint, e.g. https://your-server.example/mmolove/callback. We POST every heart.counted here. (Private / loopback / link-local URLs are rejected for SSRF safety.)
• Signing secret — click Rotate secret to mint one. It's shown once; copy it and store it where your callback handler can read it (env var / secrets manager — never the browser or game client).
• Legacy GET callback — leave off for new integrations. It exists only for older vote-callback scripts that expect a GET with query params. See Legacy GET mode.

Then click Send test callback to fire a signed heart.test at your endpoint and confirm the wiring before real votes arrive.

Reward callbacks

When a heart is counted, MMOLove delivers a signed JSON POST to your callback URL:

POST /your/callback/path
Content-Type: application/json
X-MMOLove-Event: heart.counted
X-MMOLove-Signature: t=<unix>,v1=<hex>

The body (heart.counted) is:

{
  "event": "heart.counted",
  "server_id": "8f0e…-server-uuid",
  "username": "PlayerOne",
  "heart_id": "1a2b…-heart-uuid",
  "period": "2026-06",
  "timestamp": 1733500000,
  "streak_day": 7,
  "loyalty_score": 240
}

See the Payload reference for the full contract, including the heart.test shape and how to use heart_id for idempotency.

Verifying signatures

Every callback is signed with an HMAC-SHA256 keyed by your per-server secret (rotate it any time from the Integration tab). Verify the signature before granting a reward so you only act on requests that genuinely came from MMOLove.

The signature is in the X-MMOLove-Signature header:

X-MMOLove-Signature: t=<unix>,v1=<hex>

• t — Unix seconds at delivery time (equal to the body's timestamp).
• v1 — HMAC_SHA256(secret, "<t>.<rawBody>") in lower-case hex, where rawBody is the exact request-body bytes. There is no sha256= prefix on the reward-callback v1 (this differs from the Referral Kit — see the note below).

To verify, recompute the MAC over "<t>.<rawBody>" and compare it to v1 with a constant-time comparison:

expected = HMAC_SHA256(secret, t + "." + rawBody)   // lower-case hex
trust the request  ⇔  expected == v1 (timing-safe)

Relationship to the Referral Kit signature

Both webhooks use the same HMAC core: HMAC_SHA256(secret, "<t>.<rawBody>"), lower-case hex, signed over the raw body, with t in the X-MMOLove-Signature header. The only difference is the v1 encoding:

So if you've already integrated the Referral Kit, your signing core is reusable — just strip the sha256= prefix when verifying a reward callback's v1.

See Signing & verification for the full scheme, a worked example, and a replay-window recommendation.

Read next