Webhooks

Setup

Add an endpoint in Studio → Developers: enter your HTTPS URL and select the events to subscribe to. PollsLive shows a signing secret (whsec_…) once - store it to verify deliveries.

Events

• poll.published - A poll was published and is now live/shareable.
• poll.closed - Voting was closed on a poll.
• vote.created - A new vote was recorded on an async poll.
• session.started - A live presenter session was started.
• session.ended - A live presenter session ended.
• response.created - A participant submitted a response in a live session.

Payload

Every delivery is a JSON body with the event name, a timestamp, and the event data:

{
  "event": "poll.published",
  "createdAt": "2026-06-18T12:00:00.000Z",
  "data": {
    "poll": { "id": "...", "slug": "...", "title": "...", "shareUrl": "..." }
  }
}

Each request also carries these headers:

• X-PollsLive-Event - the event name.
• X-PollsLive-Delivery - a unique delivery id.
• X-PollsLive-Signature - t=<unix>,v1=<hex>.

Verifying signatures

Compute an HMAC-SHA256 of <t>.<rawBody> using your signing secret and compare it to the v1 value (constant-time):

import crypto from "crypto";

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(",").map((kv) => kv.split("="))
  );
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(parts.v1)
  );
}

Respond with a 2xx status to acknowledge. Reject anything that fails verification.

Retries

If your endpoint is unreachable or returns a non-2xx status, PollsLive retries with exponential backoff (roughly 1m, 5m, 30m, 2h, 6h) up to six attempts. Make your handler idempotent using the X-PollsLive-Delivery id.