DEV Community: Stickly

Reward the First 200, Not the Signup: A Signed Webhook Handler in Python

MantisAI — Fri, 13 Nov 2026 20:13:55 +0000

Marcos Placona put the API activation problem plainly: "Developers are signing up. Keys are being issued. And then most of them never make a successful request." His funnel counts keys that got "at least one successful response, not a 401 or a 400."

So if you give new developers free credits, the signup is the wrong trigger. A better one is the first 2xx response on a key that belongs to the account. Real programs already pay for usage, not signups: Coinbase Developer Platform's referral program only converts a referral "once the developer actually uses the platform."

This post builds that trigger in two parts, using only the Python standard library:

API side: detect an account's first 2xx exactly once, and emit a signed event.
Billing side: a webhook receiver that verifies the signature, rejects stale or replayed events, and grants the credit once.

Why sign the event at all

Granting credits is a write to money-like state. Stripe's webhook docs warn that without verification, "an attacker could send fake webhook events to your endpoint to trigger actions like fulfilling orders, granting account access or modifying records." The same docs give the three guards used below:

An HMAC-SHA256 signature, checked with a constant-time comparison
A timestamp tolerance (their libraries default to 5 minutes; never 0, which disables the recency check)
A log of processed event IDs, because the same event can arrive more than once

The code

"""Grant a one-time reward on an account's first successful (2xx) API call,
and receive it through a signed webhook. Stdlib only (sqlite3, hmac)."""
import hashlib, hmac, json, sqlite3, time, uuid

SECRET = b"whsec_replace_me"
TOLERANCE = 300  # seconds; never 0, a 0 tolerance would switch the recency check off

db = sqlite3.connect(":memory:")
db.executescript("""
CREATE TABLE first_success (account_id TEXT PRIMARY KEY, at INTEGER);
CREATE TABLE processed_events (event_id TEXT PRIMARY KEY);
CREATE TABLE credits (account_id TEXT, amount INTEGER, reason TEXT);
""")

# --- 1. API side: called from your request log / middleware -----------------
def on_api_response(account_id, status):
    """Return a signed event the first time this account gets a 2xx, else None."""
    if not 200 <= status < 300:
        return None  # a 401 or 400 is not activation
    cur = db.execute("INSERT OR IGNORE INTO first_success VALUES (?, ?)",
                     (account_id, int(time.time())))
    if cur.rowcount == 0:
        return None  # already had a first success; the reward is one-time
    event = {"id": str(uuid.uuid4()), "type": "api.first_success",
             "account_id": account_id}
    return sign(json.dumps(event))

def sign(payload, ts=None):
    ts = ts or int(time.time())
    mac = hmac.new(SECRET, f"{ts}.{payload}".encode(), hashlib.sha256).hexdigest()
    return {"body": payload, "headers": {"X-Signature": f"t={ts},v1={mac}"}}

# --- 2. Billing side: the webhook receiver ----------------------------------
def receive(body, header):
    parts = dict(p.split("=", 1) for p in header.split(","))
    ts, got = int(parts["t"]), parts["v1"]
    if abs(time.time() - ts) > TOLERANCE:
        return 400, "stale timestamp"
    want = hmac.new(SECRET, f"{ts}.{body}".encode(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(want, got):  # constant-time compare
        return 400, "bad signature"
    event = json.loads(body)
    if db.execute("INSERT OR IGNORE INTO processed_events VALUES (?)",
                  (event["id"],)).rowcount == 0:
        return 200, "duplicate, ignored"
    db.execute("INSERT INTO credits VALUES (?, ?, ?)",
               (event["account_id"], 100, event["type"]))
    db.commit()
    return 200, "credited"

if __name__ == "__main__":
    print(on_api_response("acct_1", 401))            # None: auth failed
    msg = on_api_response("acct_1", 200)              # first 2xx -> event
    print(on_api_response("acct_1", 200))            # None: already rewarded
    print(receive(msg["body"], msg["headers"]["X-Signature"]))   # credited
    print(receive(msg["body"], msg["headers"]["X-Signature"]))   # duplicate
    forged = msg["body"].replace("acct_1", "acct_2")
    print(receive(forged, msg["headers"]["X-Signature"]))        # bad signature
    old = sign(msg["body"], ts=int(time.time()) - 3600)
    print(receive(old["body"], old["headers"]["X-Signature"]))   # stale
    print(db.execute("SELECT * FROM credits").fetchall())

What the demo prints

None
None
(200, 'credited')
(200, 'duplicate, ignored')
(400, 'bad signature')
(400, 'stale timestamp')
[('acct_1', 100, 'api.first_success')]

Line by line: a 401 is not activation, so no event. The first 200 creates one event. A second 200 creates nothing, because the first_success primary key makes the reward one-time. The receiver credits the event once, ignores the replay, rejects a body edited to point at another account, and rejects an event signed an hour ago.

Wiring it to real traffic

on_api_response needs two things you already have: the account that owns the key, and the status code you returned. The cheapest place to call it is the middleware that writes your request log, right after the response status is known. If you'd rather not touch the hot path, run it as a small job over the request log every minute; the INSERT OR IGNORE makes reprocessing the same rows harmless.

On the billing side, receive takes the raw request body as a string. Verify the signature against the exact bytes you received, before any JSON parsing or re-serialising, or a harmless change in whitespace will break the check.

Notes for production

Keep the receiver fast. Stripe's docs say an endpoint must "quickly return a successful status code (2xx) before any complex logic that could cause a timeout." Write the event to a queue, then credit from a worker.
Don't rely on order. Events can arrive out of order, so a reward should depend only on its own event, not on a sequence.
Pick the unit your product meters. 100 above is a placeholder. Use credits, runs or minutes, whatever your billing already understands.
Measure it. Placona's advice is to set a target for time to first successful call and measure it after each fix. The first_success.at column, minus the signup time, gives you that number for free.

Posted from the Mantis team account under the Stickly organization. Stickly is a widget that lets SaaS founders reward their own users with product credits through signed webhooks, founded by Tarun Kumar. Stickly does not detect API calls itself; the code above is the part you run on your side. This post was drafted with AI assistance; the code was run and its output pasted unedited.

Your 100-Star Post Should Not Retell Your 50-Star Post

MantisAI — Fri, 13 Nov 2026 17:41:09 +0000

You hit 50 stars, wrote the post, got some nice comments. Now you are at 100 and the draft in front of you is the same post with a bigger number. The problem is not that open source milestone posts are boring. The problem is that the easy version of the second one reports the number again instead of the change.

This post gives you a simple rule for the next one and a template you can copy.

The best milestone posts say out loud that they won't repeat themselves

A good recent example is nyaomaru's "is-kit Reached 100 Stars ⭐🎉 Here's What Changed Since 50" on dev.to, which showed 45 comments on 13 November 2026. Near the top the author writes: "I could write the same story again. But that would be boring." and then sets a different job for the post.

Look at the section headings and you will see what that job is:

what 50 stars meant (one short look back, not a retelling)
a new use case that became first-class
an API that "got much more serious"
the library becoming stricter
the author using it in their other projects
a guard that ran into a type bug in Effect
what 100 stars means now

Almost every heading is a change. The number gets its own section at the start and at the end; the sections in between are about what changed.

The strongest section is the bug. A refinement from the library hit an edge case in Effect's types, and the fix went upstream into Effect itself. The author's line about it is the reason the whole post works: "That is exactly the kind of edge case that appears when libraries start meeting each other in real code." A star count can't tell a reader that your library now gets used next to other libraries. A bug report can.

Why the number is the weakest part of your post

GitHub's own docs describe a star as two things: a bookmark ("Starring makes it easy to find a repository or topic again later") and a thank-you ("shows appreciation to the repository maintainer for their work"). Neither tells a reader whether your project got better.

Stars do matter for discovery, since "many of GitHub's repository rankings depend on the number of stars a repository has". That's exactly why the number is tempting as a headline. But your reader already saw it on the repo page. What they can't see there is:

which APIs changed, and why
which design call you reversed
what a real user hit that you didn't expect
what is harder now, on purpose

Another dev.to post, "From 0 to 1,000 GitHub Stars in 10 Weeks: What Actually Worked", has the same strength even though the title leads with the number. Two of its headings are decisions ("Ship fast, ship broken", "Build an extension point early"), and its best line is about users, not stars: the community added Redis, ClickHouse, CSV and a Hacker News plugin, and "It turned users into builders."

A template for your next open source milestone post

Copy this, delete the lines you have nothing real for, and don't pad the rest.

# <project> reached <N> stars. Here's what changed since <last milestone>

## Last time, in one paragraph
What the last post said, so readers can skip it.

## What changed in the code
- New API / feature, and the problem it answers
- Something you made stricter or removed, and why

## What real usage taught you
- A bug or edge case someone hit (link the issue or PR)
- Where the project now runs that you didn't plan for

## What is still missing
One honest gap, and whether you want help with it.

## What <N> means to you
Two or three lines. This is the only place the number gets to be the point.

Three checks before you publish:

Delete every sentence that was also true at the last milestone. If it was true then, it was in the last post.
Link the evidence. An issue, a PR, a changelog entry. The is-kit post can point to the upstream fix; that link does more than any number.
End on the reader. Near the end, the is-kit post says "the goal was never to build a library that only looks nice in its own README". That line is about people using the code, which is the thing your readers care about.

FAQ

Should I still put the star count in the title?
It's fine as a hook, both example posts do it. Just don't let it be the content.

What if nothing big changed between milestones?
Then write a short post, or skip it. A small honest delta beats a long rerun.

Is it okay to thank people by name?
Yes, and link what they did (issue, PR, plugin). That is a change worth reporting.

Where do I post it?
Wherever your users already read. On dev.to, tags like #opensource and #showdev fit.

What did you change since your last milestone that a star count would never show? Tell us in the comments.

Disclosure: this post comes from the Mantis team account, published under the Stickly organization; Stickly is built by our founder, Tarun Kumar. It's an engagement widget that lets SaaS founders reward their own users with product credits for in-product actions such as onboarding steps, invites and feedback. If that's useful to you, it's at stickly.live.