Overview
The reward callback — MMOLove POSTs a signed heart.counted event when a player votes, and you grant the in-game reward.
The reward callback is the vote→reward loop. A player hearts your server on
its MMOLove listing; MMOLove POSTs a signed heart.counted event to your
callback URL; you grant the in-game reward. We tell you who voted; you own the
economy.
The page you may have bookmarked, /docs/integration, is
the canonical reward-callback reference (with the #callbacks and #signatures
anchors). This section expands it into a quickstart, per-language handlers, the
legacy GET mode, testing, and a full error table.
The loop
Vote
A player taps the heart on your listing and enters their in-game username. MMOLove fraud-scores the vote and applies a 24-hour per-identity cooldown. If it counts, a delivery is queued for your server.
Deliver
A background worker POSTs a signed heart.counted to your callback URL, naming the
player, the vote (heart_id, period), and the player's current daily
streak_day.
Verify
Recompute the HMAC over the raw body, compare it to the X-MMOLove-Signature
header, and only then trust the request.
Reward
Resolve username → an account, grant the loot, return 2xx. A non-2xx or a
timeout is retried with backoff; a heart_id-keyed grant makes retries safe.
What you configure
Everything lives on your server's dashboard Integration tab:
- a public
https://callback URL, - a signing secret (minted with Rotate secret, shown once), and
- (optional, legacy only) the GET callback toggle.
Then Send test callback to confirm the wiring end-to-end before real votes arrive.
Read next
Quickstart
Zero to a verified test callback in 5 minutes.
Payload reference
Every field, the heart.test shape, idempotency via heart_id.
Signing & verification
The exact HMAC scheme + a worked example.
Legacy GET mode
The older GET-with-query-params callback.
Testing & self-verify
Send test callback + the delivery log.
Errors, retries & delivery
Retry schedule, statuses, troubleshooting.
Handler guides
Complete copy-paste handlers per stack.
SDKs
One-call verifiers for Node, PHP, Python, .NET.
Reward callbacks vs. the Referral Kit
These are two different integrations:
| Reward callback | Referral Kit | |
|---|---|---|
| Trigger | a player votes (hearts) for you | a player you referred registers / qualifies |
| Direction | MMOLove → you (we POST, you verify) | you → MMOLove (you POST, we verify) |
| You reward | the voter | the referrer |
| Event | heart.counted | registered / qualified |
They share the same HMAC core but differ in the v1 header encoding — see
Signing.
Reward callbacks
The core vote→reward webhook — a player hearts your server, MMOLove POSTs a signed heart.counted event, you grant the in-game reward.
Quickstart
From zero to a verified reward callback in about five minutes — set the URL, copy your secret, send a test callback, watch it land, then verify and reward.