Embed & API — developer docs
Embed any of the five Wheel of Item games on your own website, fire them from your backend, and receive every result server-side. Everything here needs an Embed plan or its free 14-day trial.
1 · Setup, step by step
- Design your games first. Each embed shows a game you built in the normal editors: a wheel (save it, then create its share link — the embed uses the shared wheel), a gacha template, a claw machine, a photo booth. Tarot needs no setup.
- Open Dashboard → 🧩 Embed & API (a collapsible row). Start the 14-day trial (no card) or buy the plan.
- Create API keys. You get a public key
pk_live_…(goes in your page) and a secret keysk_live_…(server-side only — shown exactly once; rotate it if lost). A webhook secret is created alongside. - Allowed domains — up to 3 hostnames (e.g.
shop.example.com, 127.0.0.1for local dev). The embed and the visitor-spin endpoint only work from these origins. - Pick what each widget shows — dropdowns list your saved wheels (shared ones), gacha templates, claw machines and photo booths. Set only the ones you use.
- Optionally set the webhook URL (https) and the visitor spins/day limit (1–50, default 3), then Save.
- Paste the snippet (below) into your page. Done.
2 · Embed the widget
<script src="https://wheelofitem.com/embed.js"
data-key="pk_live_YOUR_KEY"
data-widget="wheel"></script>
| Attribute | Values | Default |
|---|---|---|
data-widget | wheel · gacha · tarot · claw · photo | wheel |
data-height | any CSS height for the iframe | 480px |
data-button | none hides the visitor button (trigger-API-only pages) | button shown |
The loader renders an iframe (max-width 640px, centered) plus one action button — Spin / Pull / Draw / Grab / Snap depending on the widget. Use several script tags to embed several widgets on one page.
Appearance & themes
- Each widget renders with the theme, colors, prizes and weights you saved in its own editor — the embed always follows the saved design. Change the design there; embeds pick it up on the next page load (live-config changes such as switching the selected gacha template propagate automatically).
- Widget backgrounds are transparent — your page shows through, so they sit naturally on any design.
- The iframe is responsive to its container width; control height with
data-height(560px fits the gacha/claw cabinets nicely).
3 · Getting the results out (3 channels)
| Channel | Latency | Widgets | Use for |
|---|---|---|---|
| On-page animation | instant | all five | the visitor experience |
JS woi:result postMessage | instant (when the animation lands) | wheel, gacha | reacting in your page's JS |
| Signed webhook | ≤ ~1 minute | all five | recording the result in your own system — the source of truth |
3a · Page-side event (wheel & gacha)
window.addEventListener('message', function (e) {
if (e.data && e.data.type === 'woi:result') {
// wheel: { type:'woi:result', widget:'wheel', item:'Prize name' }
// gacha: { type:'woi:result', widget:'gacha', item:null, tier:'gold' } ← tier only;
// the full item name arrives in the webhook / pull record
console.log(e.data);
}
});
3b · Webhook — every result, signed
Set your https endpoint in the dashboard panel. Every pull recorded on your account (embed spins, API triggers — and your own streamer usage, if any) is delivered:
POST your-endpoint
Content-Type: application/json
X-WOI-Signature: hex sha256 HMAC of the raw body
{"event":"pull","uid":"...","pullId":"...","source":"obs_wheel",
"item":"Prize name","itemImage":null,"tier":null,"tierName":null,
"donor":"Web visitor","amount":null,"tsMillis":1756100000000}
source tells you which game produced the result:
| Widget | source | Notes |
|---|---|---|
| wheel | obs_wheel | item = winning slice label |
| gacha | obs | item = prize name, tier/tierName set; a 10× pull delivers 10 events |
| tarot | obs_tarot | item = card drawn |
| claw | obs_claw | every grab is delivered with win: true|false; a miss has item: null |
| photo booth | obs_photo | item = prize label; itemImage may carry the prize image URL |
Verify the signature (Node)
const crypto = require('crypto');
function verify(rawBody, header, webhookSecret) {
const expect = crypto.createHmac('sha256', webhookSecret).update(rawBody).digest('hex');
return crypto.timingSafeEqual(Buffer.from(expect), Buffer.from(header || ''));
}
- The webhook secret is shown with your keys in the dashboard. Rotating the secret key does not change the webhook secret.
- Respond with any 2xx. Failures are retried twice, then that event is skipped (the stream never wedges on one bad delivery).
- Consume idempotently by
pullId— a retry after a slow 2xx can deliver the same pull twice. - Wheel and gacha results from several screens watching the same widget are de-duplicated server-side (one spin = one pull). Claw / photo / tarot are typically single-screen; with multiple screens open they may deliver once per screen — consume idempotently.
4 · Trigger a spin from your server
Fires the embedded widget live for everyone currently watching the page — perfect for "signup → spin", "milestone → pull", "quest done → draw" on your own backend. Not for selling chances at prizes of value (see the Terms).
curl -X POST https://wheelofitem.com/api/v1/trigger \
-H "Authorization: Bearer sk_live_YOUR_SECRET" \
-H "Content-Type: application/json" \
-d '{"widget":"wheel","label":"New member #1042"}'
| Field | Type | Notes |
|---|---|---|
widget | wheel · gacha · gacha10 · tarot · claw · photo | default wheel; gacha10 = a 10× pull |
label | string ≤ 60 | shown on the widget's toast and recorded as the donor name |
amount | number > 0 | optional; recorded with the pull (useful to pass a score or count through to your webhook) |
Python-urllib User-Agent with a bare 403. Set your own UA — req.add_header('User-Agent', 'myshop/1.0') — or use requests. curl, Node, Go, Java, PHP and Ruby defaults all pass.5 · Visitor spin endpoint
embed.js calls this when a visitor presses the button — documented for custom buttons. Browser-only: the request's Origin must be on your allowlist.
POST https://wheelofitem.com/api/v1/embed/spin
Content-Type: application/json
{"pk":"pk_live_YOUR_KEY","widget":"wheel","visitor":"stable-id-per-visitor"}
visitor is any stable per-visitor string (embed.js keeps one in localStorage) — it keys the per-visitor daily limit. Rolls are decided server-side; a visitor cannot cheat the odds, and every screen watching shows the same result.
6 · Quotas, limits & errors
- Monthly quota (shared by all five widgets): 10,000 fires — Plus plan: 50,000. One button press or one trigger call = 1 (a
gacha10trigger counts 1 but delivers 10 webhook events). Resets monthly; the dashboard shows this month's count. - Per-visitor: your configured spins/day (1–50, default 3) → HTTP 429
visitor-limit. - Burst: server rolls and recording are rate-limited (~100–120/min per account) — bursts beyond that degrade gracefully.
- Domains: 1 website per plan, up to 3 hostnames.
| HTTP | Code | Meaning |
|---|---|---|
| 401 | auth-required / invalid-key | missing or wrong sk_live_… |
| 402 | not-entitled | plan/trial inactive — renew in the dashboard |
| 403 | domain-not-allowed | page origin not in your allowlist |
| 404 | unknown-key | pk not found |
| 409 | widget-not-configured | that widget has no wheel/template/machine/booth selected in the dashboard |
| 429 | visitor-limit / fair-use | per-visitor daily cap / monthly quota reached |
7 · Plans
| Pro | Embed Plus | |
|---|---|---|
| Monthly quota | 2,000 | 50,000 |
| Price / month | the Pro price (from ฿30 · $3 · ¥300 · ₩4,500) | ฿149 · $6.50 · ¥650 · ₩6,500 |
| Everything else | identical — all five widgets, trigger API, webhooks and full streamer Pro; price follows your country at checkout; buying Plus raises your quota at once (it never downgrades) | |
Free 14-day trial (Pro included, 2,000 spins, no card) from the dashboard panel.