ShortStack Platform Help
Step 1 — Gather context
If references/learnings.md exists, read it first for accumulated platform knowledge.
-
What are you trying to do?
- A) Read entries/leads via the Entries API (paging, newest-first)
- B) Receive entries in real time via the signed webhook (and verify
X-Ss-Signature)
- C) Sync entrants to an ESP/CRM (Mailchimp/HubSpot/Salesforce) or Zapier
- D) Pick + set up a campaign type — contest, sweepstakes, quiz, refer-a-friend, instant-win, hashtag/comment-to-enter
- E) Handle giveaway fraud / fake entries, or pick a winner fairly
- F) Decide Free vs a paid tier, or export leads
-
API or no-code? Code integration → Entries API + signed webhooks. No endpoint → native ESP/CRM connectors or Zapier.
Skip-ahead rule: if the user's prompt already provides enough context, skip to Step 2.
Step 2 — Route or answer directly
| If the question is about... | Route to... |
|---|
| Giveaway / audience-growth strategy across tools (which tool, viral mechanics) | /sales-audience-growth {question} |
| Connecting ShortStack to a CRM/ESP generically (iPaaS) | /sales-integration {question} |
| Email sequences for the list you collect | /sales-email-marketing {question} |
| Deliverability of giveaway/notification emails | /sales-deliverability {question} |
When routing, give the exact command, e.g. "This is a strategy question — run: /sales-audience-growth maximize entries on a refer-a-friend contest".
Step 3 — ShortStack platform reference
Read references/platform-guide.md for the full reference — the campaign-type + module map (what's API vs webhook vs UI-only), the entry/lead data model, plan tiers, and quick-start recipes (pull entries via the API; verify the signed webhook; sync to an ESP).
Read references/shortstack-api-reference.md for the integration surface — the Entries API (base https://entries.shortstack.com/entries, Authorization: Token token= header, per_page ≤5000, sort/direction, {data:[...]} response) and the signed webhook (X-Ss-Signature = HMAC of request body + your secret key) that fires on each new entry, plus the Webhooks management API + sandbox.
Answer using only the relevant section. Don't dump the full reference.
Step 4 — Actionable guidance
Focus on the user's specific situation:
- Read entries with the token header.
GET https://entries.shortstack.com/entries with Authorization: Token token=YOUR_API_KEY; page newest-first with sort=received&direction=descending&per_page=… (max 5000). Response is { "data": [ … ] }.
- Verify the webhook signature. ShortStack signs each webhook with
X-Ss-Signature = HMAC(request body + secret). Recompute and constant-time compare before trusting the payload — this is a real signed webhook, so use it (don't skip verification). Still dedupe on the entry id.
- Prefer a native ESP/CRM connector when you can. Mailchimp/HubSpot/Salesforce sync directly; use Zapier or the webhook only when you need custom routing.
- Pick the campaign type to the goal. Contests/sweepstakes for reach, quizzes for segmentation, refer-a-friend for virality, instant-win for engagement, hashtag/comment-to-enter for social. Winner selection is automatic.
- Plan for fraud. Viral contests attract fake/disposable entries and multi-entry abuse — validate emails before counting/rewarding and review entries before drawing a winner.
- Mind the plan. Free-forever plan exists; advanced features, entry volume, and white-labeling scale with paid tiers (best-effort — verify current pricing). ShortStack also serves big brands/agencies, so tiers run up to enterprise.
If you discover a gotcha, workaround, or tip not covered in references/learnings.md, append it there.
Gotchas
Best-effort from research (2026-06) — the help center is Cloudflare-protected, so some API/pricing specifics are from indexed sources; verify in-account.
- Entries API auth is a token header.
Authorization: Token token=YOUR_API_KEY (note the token= prefix) — not a bare bearer; a wrong format 401s.
per_page max is 5000 (default 100). For large accounts, page with sort=received&direction=descending and confirm the cursor/offset for beyond 5000 in the live docs.- The webhook IS signed — verify it.
X-Ss-Signature is an HMAC of the body + your secret. Unlike many giveaway tools (no HMAC), you can and should verify authenticity; failing to is the main security gap.
- Campaigns are UI-built. The API reads entries and manages webhooks; you don't create campaigns via API. Build them in the app.
- Help center is bot-protected. Exact endpoint catalog + entry/webhook payload schema need confirming in-account (Cloudflare blocks automated fetches).
- Contests attract fraud. Disposable emails, same-person multi-entry — validate before counting and review before awarding.
- Tiers scale to enterprise. A free plan exists, but advanced/volume/white-label features are paid; ShortStack's bigger customers are enterprise/agencies, so confirm what your tier includes.
Related skills
/sales-audience-growth — Giveaway / contest / audience-growth strategy across tools (ShortStack is one of the contest platforms covered) — viral mechanics, tool selection/sales-email-marketing — Email sequences for the list you grow with a contest/sales-integration — Connecting ShortStack to a CRM/ESP via the Entries API / webhooks / Zapier/sales-deliverability — Inbox placement and list quality for the emails you collect/sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do -a claude-code
Examples
Example 1: Pull new entries into my system via the API (developer/automation)
User says: "How do I fetch the latest entries from my ShortStack campaign programmatically?"
Skill does: Shows GET https://entries.shortstack.com/entries with the Authorization: Token token=YOUR_API_KEY header, using sort=received&direction=descending&per_page=50 to get newest-first (max 5000), and parsing the { "data": [ … ] } response. Notes the API reads entries (campaigns are UI-built) and recommends the signed webhook for real-time instead of polling.
Result: A working, paged pull of the campaign's entries.
Example 2: Verify the entry webhook so I can trust it
User says: "ShortStack is POSTing entries to my endpoint — how do I make sure they're really from ShortStack?"
Skill does: Explains the X-Ss-Signature header is an HMAC of the request body + your secret key; the handler should recompute the HMAC over the raw body and constant-time compare to the header, rejecting on mismatch. Adds dedupe on the entry id (retries) and treating the endpoint as secret. Notes Zapier as a no-code alternative if they don't want to host an endpoint.
Result: Authenticated, tamper-evident webhook intake.
Example 3: Which campaign type — and how do entries flow to my ESP?
User says: "I want a refer-a-friend giveaway that adds entrants to Mailchimp. What do I pick?"
Skill does: Recommends the refer-a-friend campaign type for virality and the native Mailchimp connection (direct) so entrants sync automatically — or Zapier/the webhook for custom routing. Flags double-opt-in + fraud filtering before nurture, automatic winner selection at the end, and routes deeper viral-mechanics strategy: "run: /sales-audience-growth maximize referrals on a giveaway."
Result: The right campaign type wired to the user's ESP.
Troubleshooting
My Entries API calls return 401
Symptom: Requests to entries.shortstack.com/entries are rejected as unauthorized.
Cause: The auth header is malformed — ShortStack expects Authorization: Token token=YOUR_API_KEY (the literal Token token= prefix), not Bearer ... or a bare key.
Solution: Send exactly Authorization: Token token=YOUR_API_KEY (key from account settings), over HTTPS, to https://entries.shortstack.com/entries. Test with curl -i -H "Authorization: Token token=$API_KEY" "https://entries.shortstack.com/entries?per_page=25".
My webhook signature check keeps failing
Symptom: The HMAC you compute doesn't match X-Ss-Signature.
Cause: Signing over a re-serialized/parsed body instead of the raw bytes, a wrong secret, or the wrong HMAC encoding.
Solution: Compute the HMAC over the raw request body (before any JSON parsing) using your shared secret key, match the encoding ShortStack uses, and constant-time compare to X-Ss-Signature. Capture a live delivery to confirm the exact scheme (the help center is bot-protected). Once verified, dedupe on the entry id.
My contest is full of fake entries
Symptom: A spike of disposable-email or duplicate entries.
Cause: Viral contests attract fraud — disposable emails, multi-entry, bots.
Solution: Validate/verify emails before counting, watch for same-person multi-entry, add friction (double opt-in), and review entries before the automatic winner draw. For list quality/deliverability afterward, use /sales-deliverability.
