Wire Puzzel into your own platform

Which channel do you need?

Three things can leave an activity and one can come in. Which one fits depends on a single question: does the player sit inside your page, or somewhere else entirely?

Results webhook

Switch on "Send results to a webhook" in the builder and give it a URL. From then on, every time the player's progress is saved, their browser POSTs the whole result to that URL as JSON.

import express from 'express';

const app = express();

// The POST is made by the player's browser, so the browser asks permission
// first. Answer the preflight and the real request can land.
app.use((req, res, next) => {
  res.set('Access-Control-Allow-Origin', 'https://puzzel.org');
  res.set('Access-Control-Allow-Headers', 'Content-Type');
  if (req.method === 'OPTIONS') return res.sendStatus(204);
  next();
});

app.post('/puzzel/results', express.json(), async (req, res) => {
  const result = req.body;

  // One run posts several times as it goes. Key on the pair, not on an
  // insert: each call carries the whole state, so the newest simply wins.
  await db.results.upsert(
    { playerUid: result.playerUid, activityKey: result.activityKey },
    result
  );

  // Only act on the finish once.
  if (result.progress >= 100 || result.hasAlternateCompletion) {
    await markCourseStepComplete(result);
  }

  res.sendStatus(200);
});

Results to the page around it

If you embed the activity, you can have that same JSON posted to your own page instead of to a server. Switch on "Send results to the parent page" and listen for the message. Nothing leaves the browser, so there is no endpoint to build and no CORS to think about.

<iframe
  src="https://puzzel.org/en/quiz/embed?p=-Nq8sample_activity_key"
  width="100%"
  height="700"
  frameborder="0"
  allowfullscreen
></iframe>

<script>
  window.addEventListener('message', (event) => {
    if (event.origin !== 'https://puzzel.org') return;

    const result = event.data;
    if (!result || !result.activityKey) return;

    // Same shape the webhook posts, same advice: it arrives repeatedly.
    saveProgress(result);
  });
</script>

Completion signal

The smallest channel, for when the result itself is none of your business: switch on "Post a completion signal" and your page gets one message the moment the player finishes.

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://puzzel.org') return;
  if (event.data?.completed !== true) return;

  // { completed: true, activityKey: '-Nq8sample_activity_key' }
  unlockNextLesson(event.data.activityKey);
});

{
  "completed": true,
  "activityKey": "-Nq8sample_activity_key"
}

What a result contains

One shape, whichever channel carries it. The player's answers are keyed by the activity's own item ids, so the same keys turn up in correctUids.

{
  "activityKey": "-Nq8sample_activity_key",
  "playerUid": "kK3r9TzSampleAnonymousUid",
  "player": {
    "name": "Ava Ortega",
    "email": "ava@school.example",
    "class": "5B"
  },
  "progress": 100,
  "timePassed": 243120,
  "lastPlayedAt": 1758297843120,
  "createdAt": 1758297600000,
  "playerInput": {
    "-Nq8item_one": "Lisbon",
    "-Nq8item_two": "1969"
  },
  "correctUids": {
    "-Nq8item_one": true,
    "-Nq8item_two": false
  },
  "score": 800,
  "contentVersion": 1757923200000
}

Resetting the activity from your page

One instruction travels the other way. With "Accept triggers from the parent page" switched on, the page doing the embedding can clear the player's answers and put the activity back to the start — for a "try again" button of your own, outside the frame.

const frame = document.querySelector('iframe').contentWindow;

// Sent to the frame, from the page that embeds it — no other sender is
// accepted, and the activity has to have the trigger setting switched on.
frame.postMessage({ trigger: { type: 'reset' } }, 'https://puzzel.org');

Bringing your own player identity

If your platform already knows who is playing, the activity does not have to ask them again. Two handshakes exist, both for an activity inside your page, and both switched on by us rather than in the builder — they change who a result belongs to, so they are set up with you rather than from a checkbox.

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://puzzel.org') return;

  // The activity says it is ready for a player.
  if (event.data === 'app-loaded') {
    frame.postMessage(
      {
        player: { name: 'Ava Ortega', email: 'ava@school.example', class: '5B' },
        // true starts a fresh attempt instead of resuming this player's last one
        should_reset: false
      },
      'https://puzzel.org'
    );
  }

  // Signed in; the board is coming.
  if (event.data?.success === true) hideYourOwnSpinner();
});

Creating activities from your system

Everything above is about a result coming out. Going the other way — making the activities themselves from content you already have — is the Puzzle API: one POST per activity type, and you get back a key and a URL to embed.

When a ready-made connector is the better answer

If the platform on the other side is a real LMS, you probably do not need any of this. Grades can go back to its gradebook on their own, with nothing for you to host.

What there isn't

So you don't go looking for it:

• No endpoint for reading results back. The API creates activities; results leave through the channels on this page, or through the exports in your dashboard.
• No signature on the webhook. There is nothing to verify the request against, which is why a result should not be the only thing standing behind something that matters.
• No account-wide webhook. The URL is a setting on an activity, so an activity you copy carries it along and a new one starts without it.
• Nothing in a team game or a live room. Both message channels and the webhook are for solo play, and the settings turn themselves off when team play is on.
• No delivery queue. Nothing is stored and resent — the next save is the retry, and the run's last call is the one that matters.