Events API

Count an action by posting it to your project's webhook from your server or an automation. Zapier, Make, n8n, Pipedream and anything else that can send an HTTP POST works. Server-to-server ingest always uses this endpoint.

Actions are never counted from the browser. The widget only displays progress.

Count an action

POST /v1/webhook/YOUR_PROJECT_KEY/e HTTP/1.1
Host: api.streakfox.com
Content-Type: application/json
X-Streak-Webhook-Secret: YOUR_WEBHOOK_SECRET

{
  "event": "lesson_complete",
  "userHash": "member_123",
  "idempotencyKey": "lesson_42:member_123"
}

Find the webhook URL and secret in onboarding on the Connect the action step, or later under Programs → Connections. Your project key is already in the URL.

curl -X POST https://api.streakfox.com/v1/webhook/YOUR_PROJECT_KEY/e \
  -H "Content-Type: application/json" \
  -H "X-Streak-Webhook-Secret: $STREAKFOX_WEBHOOK_SECRET" \
  -d '{"event":"lesson_complete","userHash":"member_123","idempotencyKey":"lesson_42:member_123"}'

Body fields

Field	Type	Required	Description
`event`	string	Yes	Your action, such as `lesson_complete`. It must match the action on your program.
`userHash`	string	Yes	Your member ID. Use the same stable ID every time. Hash emails or internal IDs first.
`idempotencyKey`	string	Recommended	A unique ID for this one completion. Retries with the same key count once.
`ts`	ISO 8601	No	When the action happened. Defaults to when Streakfox receives it.
`meta`	object	No	Your own details for analytics, such as `{"courseId": "course_123"}`. Max about 4KB.
`externalService`	string	No	Where the action came from, such as `zapier` or `make`. Shows up in source breakdowns.
`integrationId`	string	No	A stable name for this integration, such as `course-complete-zap`.
`siteKey`	string	No	Your project key. It defaults from the URL, so you can leave it out.

Test and live

Before your program goes live, every action it receives counts as a test. You don't need to flag anything. Test progress never triggers real member follow-ups.

Going live needs one real action from your site or sender, not the dashboard, that moved a member's progress. After that, every action counts for real.

Response

A 202 with {"ok": true} means Streakfox has the action.

Errors

Errors come back as {"error": "CODE"}.

Status	Code	What to do
401	`WEBHOOK_SECRET_REQUIRED`	The secret is missing or wrong. Copy it again from Programs → Connections into `X-Streak-Webhook-Secret`.
400	`INVALID_WIDGET_KIND`	No program counts that action. Check `event` matches your program's action exactly.
400	`INVALID_BODY`	The body isn't valid JSON or is missing `event` or `userHash`. Check the JSON and the `Content-Type` header.
400	`INVALID_SITE_KEY`	The project key in the URL doesn't exist. Copy the webhook URL again.
400	`SITE_KEY_MISMATCH`	`siteKey` in the body doesn't match the URL. Remove `siteKey` from the body.
413	`PAYLOAD_TOO_LARGE`	`meta` is too big. Keep it under about 4KB.
409	`IDEMPOTENCY_KEY_IN_PROGRESS`	The same completion is still being processed. Retry after 1 second.

Read a member's streak

The widget calls this for you. Use it directly if you build your own display.

GET /v1/state?siteKey=YOUR_PROJECT_KEY&userHash=MEMBER_ID&event=lesson_complete HTTP/1.1
Host: api.streakfox.com

Query parameters

Param	Required	Description
`siteKey`	Yes	Your project key
`userHash`	Yes	Your member ID
`event`	Yes	Your action

Browser requests must come from your website address saved in Streakfox. A browser on another site gets 403 FORBIDDEN_ORIGIN.

Response

{
  "meta": {
    "apiVersion": "1",
    "isLive": true
  },
  "streak": {
    "mode": "continuous",
    "current": 5,
    "best": 12,
    "todayDone": true,
    "pending": false
  },
  "week": [
    {
      "isoDate": "2024-01-08",
      "label": "Mon",
      "dayNumber": 8,
      "isToday": false,
      "isCheckedIn": true
    }
    // ... 7 days total
  ],
  "milestones": [
    { "id": "ms_1", "target": 7, "msg": "1 week!", "achieved": false, "rewardType": "message" }
  ],
  "settings": {
    "theme": { "name": "beige" },
    "position": "bottom-right",
    "mainMessage": "Keep your streak going!"
  }
}

Coupon and link reward values stay hidden unless the request carries a signed identity token. The WordPress plugin handles this for you. See Authentication.

Usage limits

Plan	Active streakers / month
Starter	500
Growth	2,500
Scale	10,000
Pro	50,000

An active streaker is a unique member with at least one counted action in the month.

If you go over your plan's limit, nothing breaks for your members. Actions are still accepted and streaks keep counting. Dashboard reports (Overview, Events and Insights) pause until you upgrade, then show everything that was tracked in the meantime. Proof stays available so you can always read or stop a running experiment.

Next steps

Quickstart: connect, test and go live
Automations and webhooks: Zapier, Make, n8n and Pipedream, plus outbound follow-ups
Programs: cadence, targets and milestones
WordPress: counting without code

On this page