Participating in a contest? Visit this resource

Put it on your site

Postbacks & conversion tracking

Running ads to your contest? Postbacks tell your own server — or your ad network — the moment a visitor signs up or completes an action, with your campaign values (like a click ID) attached, so you can match spend to results.

A postback is a small JSON message Winzos sends to a URL you give us. You choose which events send one. Nothing changes for participants: they just use the widget as usual.

Set up a postback

  1. Open Postbacks. In your dashboard sidebar, go to Settings → Postbacks.
  2. Click Add postback. Give it a name you'll recognize, like your campaign or network.
  3. Paste your URL. It must start with https:// and be able to receive a POST with a JSON body.
  4. Pick the contest and events. One postback can cover every contest, or just one. Most people start with Signed up and Action completed.
  5. Copy the signing secret. It's shown once. You'll use it to check that messages really came from Winzos (see below).
  6. Click Test. We send a test message straight away, and Recent deliveries shows what your server answered.
Changed your mind? The switch on each postback pauses it. Paused postbacks receive nothing, and events aren't saved up for later. You can have up to 10 postbacks.

Pass your own values through

Add data-winzos-meta-* attributes to the widget mount point (the <div> from your embed code). The part after meta- becomes the field name, and every postback for that visitor carries the values in custom:

HTML
<div data-winzos-contest="3f2b8c1e-9a4d-4e7b-b1c2-5d6e7f8a9b0c" data-winzos-meta-click-id="cmp-88213" data-winzos-meta-source="spring-sale"></div>

Building the page with code? Your ad platform usually fills these in per click, the same way it fills tracking links. Up to 20 values ride along, and they stick with the participant: even when an action completes hours later, its postback still has them.

Events

EventWhen it fires
user.signed_upA new participant joins a contest.
user.signed_inA returning participant signs in.
user.signed_outA participant signs out of the widget.
action.startedA participant opens a way to earn.
action.completedEntries are credited. Includes entries_earned and your payout. This is the conversion event.
widget.viewedThe widget loads on a page. Once per visit.
widget.openedA visitor opens the widget. Once per visit.
contest.endedA contest ends — including when you end it early from the dashboard. Includes the winners (with contact details and their custom values), entry stats and your earnings. See below.
winner.claimedA winner claims their prize.
winner.forfeitedA winner loses the prize (for example, they live somewhere contests aren't open) and someone else is drawn. Names the replacement.

What you receive

Each event is an POST with a JSON body like this (action.completed shown):

JSON
{
  "event": "action.completed",
  "event_id": "9d2f0c44-1a2b-4c3d-9e4f-0123456789ab",
  "occurred_at": "2026-11-08T15:04:05.000Z",
  "contest": { "public_id": "3f2b8c1e-9a4d-4e7b-b1c2-5d6e7f8a9b0c", "name": "Fall Giveaway" },
  "user": { "id": "1042", "email": "sam@example.com" },
  "action": { "offer_ref": null, "type": "offer", "title": null, "provider_host": null },
  "entries_earned": 25,
  "payout": { "amount_usd": 1.50, "currency": "USD" },
  "custom": { "click_id": "cmp-88213", "source": "spring-sale" }
}

Answer with any 2xx status (200 is fine) and an empty or small body. The same event_id is also sent as the Idempotency-Key header: if you ever receive a retry, it carries the same ID, so you can safely ignore a copy you've already handled.

Example payloads, event by event

Every payload has the same envelope — event, event_id, occurred_at, contest, user, action, entries_earned, payout and custom — with fields that don't apply set to null. The examples below use the same contest and campaign values throughout, so you can follow one participant from first view to winner.

user.signed_up — a new participant joins

JSON
{
  "event": "user.signed_up",
  "event_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "occurred_at": "2026-11-08T14:02:11.000Z",
  "contest": { "public_id": "3f2b8c1e-9a4d-4e7b-b1c2-5d6e7f8a9b0c", "name": "Fall Giveaway" },
  "user": { "id": "1042", "email": "sam@example.com" },
  "action": null,
  "entries_earned": null,
  "payout": null,
  "custom": { "click_id": "cmp-88213", "source": "spring-sale" }
}

This is the signup conversion most campaigns optimize for: match custom.click_id to the click your ad platform recorded.

user.signed_in — a returning participant

JSON
{
  "event": "user.signed_in",
  "event_id": "3a7f1c2e-91ab-4c8d-b2e3-5f6a7b8c9d0e",
  "occurred_at": "2026-11-08T18:40:03.000Z",
  "contest": { "public_id": "3f2b8c1e-9a4d-4e7b-b1c2-5d6e7f8a9b0c", "name": "Fall Giveaway" },
  "user": { "id": "1042", "email": "sam@example.com" },
  "action": null,
  "entries_earned": null,
  "payout": null,
  "custom": { "click_id": "cmp-88213", "source": "spring-sale" }
}

Same shape as a signup — only the event name differs, so returning visits never inflate your signup count. The participant's original custom values are kept, even if this visit arrived without them.

user.signed_out — a participant leaves

JSON
{
  "event": "user.signed_out",
  "event_id": "7c3d9e1a-2b4f-4a6c-9d1e-3f5a7b9c1d2e",
  "occurred_at": "2026-11-08T18:42:57.000Z",
  "contest": { "public_id": "3f2b8c1e-9a4d-4e7b-b1c2-5d6e7f8a9b0c", "name": "Fall Giveaway" },
  "user": { "id": "1042", "email": "sam@example.com" },
  "action": null,
  "entries_earned": null,
  "payout": null,
  "custom": { "click_id": "cmp-88213", "source": "spring-sale" }
}

action.started — a participant opens a way to earn

JSON
{
  "event": "action.started",
  "event_id": "9e5b3d7f-1a3c-4e6a-8c2d-4f6a8b0c2d4e",
  "occurred_at": "2026-11-08T14:03:45.000Z",
  "contest": { "public_id": "3f2b8c1e-9a4d-4e7b-b1c2-5d6e7f8a9b0c", "name": "Fall Giveaway" },
  "user": { "id": "1042", "email": "sam@example.com" },
  "action": {
    "offer_ref": "prime:9f8e7d6c",
    "type": "offer",
    "title": "Install and open the app",
    "provider_host": "offers.example.com"
  },
  "entries_earned": null,
  "payout": null,
  "custom": { "click_id": "cmp-88213", "source": "spring-sale" }
}

offer_ref is the offer's lasting identity (provider:id); surveys have none and send null. A start is intent, not a conversion — the same participant may start actions they never finish.

action.completed — entries credited (the conversion)

Shown in full above. Two things to know in practice: it can arrive minutes or hours after action.started (the participant finishes elsewhere, and the provider tells us), and action.title/offer_ref may be null when the provider's confirmation doesn't name the offer — entries_earned and payout.amount_usd are always the source of truth.

widget.viewed and widget.opened — engagement

JSON
{
  "event": "widget.viewed",
  "event_id": "b7d9f1a3-5c7e-4a9b-9e3f-5a7c9e1b3d5f",
  "occurred_at": "2026-11-08T14:01:58.000Z",
  "contest": { "public_id": "3f2b8c1e-9a4d-4e7b-b1c2-5d6e7f8a9b0c", "name": "Fall Giveaway" },
  "user": null,
  "action": null,
  "entries_earned": null,
  "payout": null,
  "custom": {}
}

Viewers are usually signed out, so user is null and custom is empty — these events measure reach, not people. Each fires once per visitor session (a page load for widget.viewed; opening the pop-up for widget.opened, which has the same shape with that event name). Inline widgets count as opened when they load.

winner.claimed — a winner claims

JSON
{
  "event": "winner.claimed",
  "event_id": "d3f5a7c9-1e3b-4d9f-8a2c-6e8b0d2f4a6c",
  "occurred_at": "2026-11-09T09:15:30.000Z",
  "contest": { "public_id": "3f2b8c1e-9a4d-4e7b-b1c2-5d6e7f8a9b0c", "name": "Fall Giveaway" },
  "user": { "id": "1042", "email": "sam@example.com" },
  "action": null,
  "entries_earned": null,
  "payout": null,
  "custom": { "click_id": "cmp-88213", "source": "spring-sale" },
  "winners": [{
    "rank": 1, "status": "claimed", "total_entries": 40,
    "user": { "id": "1042", "first_name": "Sam", "last_name": "Lee", "email": "sam@example.com" },
    "custom": { "click_id": "cmp-88213", "source": "spring-sale" }
  }]
}

Shipping details are not included — the claim flow in your dashboard owns those. This event is your cue that a prize is ready to fulfill.

winner.forfeited — a winner loses the prize, someone else is drawn

JSON
{
  "event": "winner.forfeited",
  "event_id": "e9b1d3f5-7a9c-4e2b-9f4a-8c6e0b2d4f6a",
  "occurred_at": "2026-11-09T09:20:14.000Z",
  "contest": { "public_id": "3f2b8c1e-9a4d-4e7b-b1c2-5d6e7f8a9b0c", "name": "Fall Giveaway" },
  "user": { "id": "1042", "email": "sam@example.com" },
  "action": null,
  "entries_earned": null,
  "payout": null,
  "custom": { "click_id": "cmp-88213", "source": "spring-sale" },
  "winners": [{
    "rank": 1, "status": "forfeited", "total_entries": 40,
    "user": { "id": "1042", "first_name": "Sam", "last_name": "Lee", "email": "sam@example.com" },
    "custom": { "click_id": "cmp-88213", "source": "spring-sale" }
  }],
  "replacement_winner": {
    "rank": 1, "status": "pending", "total_entries": 35,
    "user": { "id": "1077", "first_name": "Jo", "last_name": "Kim", "email": "jo@example.com" },
    "custom": {}
  },
  "forfeiture_place": "California"
}

Never fulfill from contest.ended alone: wait for winner.claimed, and let winner.forfeited cancel anything you queued for the first winner. replacement_winner is null when nobody eligible was left to draw.

The test event

Test sends "event": "postback.test" with "test": true and everything else null/empty. Handle it by answering 200 and ignoring it in your reports.

When a contest ends

Ending a contest — on schedule, or early from End contest early on your dashboard — sends contest.ended once, with everything you need to close the loop:

JSON
{
  "event": "contest.ended",
  "contest": {
    "public_id": "3f2b8c1e-9a4d-4e7b-b1c2-5d6e7f8a9b0c",
    "name": "Fall Giveaway",
    "ended_early": true,
    "ended_early_reason": "Sold out early",
    "no_draw": false
  },
  "stats": {
    "participants": 10,
    "qualified_participants": 8,
    "total_entries": 95,
    "avg_entries_per_participant": 9.5,
    "winners_selected": true
  },
  "earnings": { "payout_usd": 25.00 },
  "winners": [{
    "rank": 1, "status": "pending", "total_entries": 40,
    "user": { "id": "1042", "first_name": "Sam", "last_name": "Lee", "email": "sam@example.com" },
    "custom": { "click_id": "cmp-88213" }
  }]
}

Winners start as pending. When one claims, you get winner.claimed; if a winner can't claim and someone else is drawn, winner.forfeited names both people, so you never ship a prize to the wrong person. If a contest ends below its minimum number of entrants, winners is empty and no_draw is true.

Check it really came from Winzos

Every delivery carries a Winzos-Signature header that looks like t=1762466645,v1=9f86d0…. To verify it:

  1. Take the timestamp (t) and the raw request body, exactly as received.
  2. Compute HMAC-SHA256 of timestamp.body (the timestamp, a dot, then the body) using your signing secret.
  3. Compare your result with v1. If they differ, the message didn't come from us — ignore it.
Verify before you trust a conversion. Anyone who learns your URL could otherwise send you fake events. If your secret ever leaks, use New secret on the postback and update your server.

Retries and the delivery log

If your server is down or answers with an error, we retry with growing waits (a minute, then 5 minutes, 30 minutes, 2 hours) before marking the delivery failed. Settings → Postbacks → Recent deliveries shows every send, your server's answer, and a Retry button for failed ones. Deliveries time out after 10 seconds, so answer quickly and do any slow work after responding.

See it all in Activity

Dashboard → Activity shows signups, starts, completions and widget engagement across all your contests, whether or not any postback received them. It's the quickest way to check a contest is behaving before you wire up a server.

What's next?

Customize the widget so it looks right at home on your site.