Automations And Webhooks

This guide covers inbound events from automation tools into Streakfox. Use the program webhook endpoint when Zapier, Pipedream, n8n, Make, or another system needs to count an action toward a program:

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

{
  "event": "lesson_complete",
  "userHash": "member_123",
  "idempotencyKey": "lesson_42:member_123",
  "externalService": "zapier",
  "integrationId": "course-complete-zap",
  "meta": {
    "courseId": "course_123"
  }
}

Required Fields

Source Labels

Set externalService and integrationId so analytics can show where events came from.

Common values:

• zapier
• pipedream
• n8n
• make
• shopify
• github-actions
• internal-cron

Your project key is already in the URL, so leave siteKey out of the body. Your own backend uses this same endpoint. See the Events API for every error and its fix.

Outbound Action Webhooks

The dashboard Programs page also has an Action webhook section for Streakfox outputs. When an action webhook is enabled for a program, Streakfox queues signed deliveries for the selected event types:

Retention delivery currently supports daily continuous streaks. Non-daily retention cadence delivery remains a follow-up.

Set up a follow-up that reaches the right member

1. In Programs → Follow-up, choose Keep a streak going, Welcome a member back, Celebrate a milestone or Deliver an earned reward. The suggested message is copied for you.
2. Create a webhook receiver in your own backend or automation platform. Paste its HTTPS URL into Streakfox and save.
3. Copy the Signing secret into the receiver’s private configuration. This is the outbound signing secret, not the secret used to send actions into Streakfox.
4. Verify the signature against the exact raw request body before parsing or acting on the event. Verify the timestamp is within five minutes of your clock.
5. Resolve subject.userId (or subject.anonymousId when applicable) to the member’s contact in your own system. Streakfox supplies pseudonymous identities, not email addresses. If there is no verified contact mapping, skip delivery.
6. Store payload.id or X-Streakfox-Delivery in a unique delivery ledger. A retry must not send a second reward or message. Return a successful response for a delivery already handled.
7. Choose Send test in Streakfox. A webhook.test event verifies the connection and must not send a real member message. Then exercise an owned test identity through your provider before enabling real sends.
8. Save the selected events and enabled state. Review Recent deliveries for success, pending retries or failure. Pausing the program or follow-up also suppresses queued member sends.

A 2xx receiver response proves that your endpoint accepted the event. It does not prove an email reached an inbox or that a reward was redeemed. Keep delivery and redemption visibility in the provider that performs those actions.

Signature verification

This example uses Node’s built-in crypto module. Pass the raw body string, not JSON that has been parsed and re-serialized.

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyStreakfox(rawBody: string, timestamp: string, signature: string, secret: string) {
  if (!/^\d+$/.test(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = `v1=${createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex")}`;
  const actualBytes = Buffer.from(signature);
  const expectedBytes = Buffer.from(expected);
  return actualBytes.length === expectedBytes.length && timingSafeEqual(actualBytes, expectedBytes);
}

Headers are X-Streakfox-Timestamp, X-Streakfox-Signature, X-Streakfox-Delivery and X-Streakfox-Event. Secrets belong in the receiver’s credential store. Rotating the secret requires updating both sides.

Suggested messages

Use your provider’s contact preferences and sending schedule. A daily streak becomes at risk on the calendar day after the last action, and broken after a missed day, in the project timezone. The hourly scan emits each transition once. Cumulative programs do not expire.

Control members in an active Proof experiment do not receive these Streakfox events. Do not add a parallel reminder workflow that ignores the experiment assignment.