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

  1. 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.
  2. Open Dashboard → 🧩 Embed & API (a collapsible row). Start the 14-day trial (no card) or buy the plan.
  3. Create API keys. You get a public key pk_live_… (goes in your page) and a secret key sk_live_… (server-side only — shown exactly once; rotate it if lost). A webhook secret is created alongside.
  4. Allowed domains — up to 3 hostnames (e.g. shop.example.com, 127.0.0.1 for local dev). The embed and the visitor-spin endpoint only work from these origins.
  5. 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.
  6. Optionally set the webhook URL (https) and the visitor spins/day limit (1–50, default 3), then Save.
  7. 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>
AttributeValuesDefault
data-widgetwheel · gacha · tarot · claw · photowheel
data-heightany CSS height for the iframe480px
data-buttonnone 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.

Photo booth asks the visitor for camera permission inside the iframe (it takes a real photo, then draws a prize). Serve your page over https or the browser will block the camera.

Appearance & themes

3 · Getting the results out (3 channels)

ChannelLatencyWidgetsUse for
On-page animationinstantall fivethe visitor experience
JS woi:result postMessageinstant (when the animation lands)wheel, gachareacting in your page's JS
Signed webhook≤ ~1 minuteall fiverecording 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:

WidgetsourceNotes
wheelobs_wheelitem = winning slice label
gachaobsitem = prize name, tier/tierName set; a 10× pull delivers 10 events
tarotobs_tarotitem = card drawn
clawobs_clawevery grab is delivered with win: true|false; a miss has item: null
photo boothobs_photoitem = 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 || ''));
}

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"}'
FieldTypeNotes
widgetwheel · gacha · gacha10 · tarot · claw · photodefault wheel; gacha10 = a 10× pull
labelstring ≤ 60shown on the widget's toast and recorded as the donor name
amountnumber > 0optional; recorded with the pull (useful to pass a score or count through to your webhook)
A trigger fires the live widget. If nobody has the page (or an OBS source) open at that moment, nothing animates and no result is produced — for guaranteed processing drive spins from a page you keep open, or call the trigger only when your own page is showing the widget.
🐍 Python stdlib users: our edge firewall rejects the default 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

HTTPCodeMeaning
401auth-required / invalid-keymissing or wrong sk_live_…
402not-entitledplan/trial inactive — renew in the dashboard
403domain-not-allowedpage origin not in your allowlist
404unknown-keypk not found
409widget-not-configuredthat widget has no wheel/template/machine/booth selected in the dashboard
429visitor-limit / fair-useper-visitor daily cap / monthly quota reached

7 · Plans

ProEmbed Plus
Monthly quota2,00050,000
Price / monththe Pro price (from ฿30 · $3 · ¥300 · ₩4,500)฿149 · $6.50 · ¥650 · ₩6,500
Everything elseidentical — 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.

Embed product page · Open dashboard