DEV Community: Anand Rathnas

Referral Tracking for Indie Hackers: Skip the $300/mo Tools

Anand Rathnas — Thu, 19 Mar 2026 01:35:44 +0000

I needed referral tracking for my SaaS. The options were depressing.

When I checked (early 2026): ReferralCandy started at $59/mo, designed for e-commerce. Rewardful at $29/mo, but that's just the starting tier. FirstPromoter and PartnerStack were priced for larger teams.

I'm a solo founder. My MRR is in the hundreds, not thousands. Every dollar saved is another month of runway.

Here's the thing: I don't need a referral platform. I need to know which users came from which invite link. That's it.

What I Actually Needed

Let me break down the "enterprise referral solution" into what matters:

Unique links per referrer - So I know who sent them
Click tracking - How many people clicked
Attribution - Connect the click to a signup

The first two are literally what URL shorteners do. The third is a query parameter and some code.

The Setup

I created invite links using jo4.io:

https://jo4.io/invite-sarah → myapp.com/signup?ref=sarah
https://jo4.io/invite-mike  → myapp.com/signup?ref=mike
https://jo4.io/invite-alex  → myapp.com/signup?ref=alex

Each referrer gets a memorable short link. Jo4 tracks clicks automatically. My signup form reads the ref parameter and stores it.

Total cost: $0 (free tier covers this easily).

The Analytics I Get

For each invite link, jo4 shows me:

Total clicks - How many people hit the link
Unique visitors - Deduplicated by IP
Geographic breakdown - Where clicks came from
Device/browser - Mobile vs desktop
Referrer - Where the link was shared (Twitter, email, etc.)
Timeline - When clicks happened

This is more data than I had with the $59/mo tool I tried last year.

Handling Attribution

On my signup page:

// Grab the ref parameter
const params = new URLSearchParams(window.location.search);
const referrer = params.get('ref');

if (referrer) {
  // Store it for the signup request
  localStorage.setItem('referrer', referrer);
}

On signup submission:

const referrer = localStorage.getItem('referrer');

await fetch('/api/signup', {
  method: 'POST',
  body: JSON.stringify({
    email,
    password,
    referredBy: referrer || null
  })
});

That's it. Now I have a referred_by column in my users table.

What About Rewards?

"But what about paying out referral bonuses?"

I run a report once a month:

SELECT referred_by, COUNT(*) as signups
FROM users
WHERE referred_by IS NOT NULL
AND created_at > NOW() - INTERVAL '30 days'
GROUP BY referred_by
ORDER BY signups DESC;

Then I send PayPal/Wise payments manually. At my scale (< 50 referrals/month), this takes 10 minutes.

When I'm at 500 referrals/month, I'll automate it. Or I'll pay for a tool. But I'll also have the revenue to justify it.

Advanced: UTM Tracking

For power referrers who share on multiple platforms, I give them UTM-tagged variants:

https://jo4.io/sarah-twitter → myapp.com/signup?ref=sarah&utm_source=twitter
https://jo4.io/sarah-youtube → myapp.com/signup?ref=sarah&utm_source=youtube
https://jo4.io/sarah-newsletter → myapp.com/signup?ref=sarah&utm_source=newsletter

Now I know not just WHO referred them, but WHERE. Jo4's analytics show me which links perform best.

The Numbers

After 3 months with this setup:

47 referral signups tracked
$0 spent on referral tools
$2,820 saved vs. the "affordable" option
10 minutes/month on manual payouts

The enterprise tools have dashboards and automation. I have a SQL query and a spreadsheet. At my scale, that's the right tradeoff.

When to Upgrade

I'll pay for a real referral platform when:

Referral volume exceeds 100/month (manual payouts become painful)
I need tiered rewards (different rates for different referrers)
Compliance requires audit trails I can't build myself

Until then, a URL shortener with analytics does 80% of the job at 0% of the cost.

Running a referral program on a budget? Share your setup in the comments.

Building jo4.io - URL shortener with analytics that indie hackers actually use for invite links, affiliate tracking, and campaign attribution.

20 Free Developer Tools We Built (And Why We Gave Them Away)

Anand Rathnas — Tue, 17 Mar 2026 01:35:06 +0000

You know those random utility websites you visit once, use for 30 seconds, and never think about again?

We built 20 of them. And put them all in one place at jo4.io/u.

No signup. No ads. No "subscribe to access." Just tools.

Why Build Free Tools on a Paid Product?

We're a URL shortener. People pay us for short links, analytics, and QR codes. So why give away free tools?

1. We Needed Them

This is the honest answer. While building jo4, we constantly needed:

JWT decoder to debug OAuth tokens
Base64 encoder/decoder for API payloads
JSON formatter to read webhook responses
Timestamp converter to debug expiration issues
Hash generator for testing HMAC signatures

We were opening random websites, getting hit with ads and popups, and thinking "this is stupid." So we built our own.

2. We're Developer-Friendly

Our tagline is literally "Built for developers who ship." If we're going to claim that, we need to prove it.

Free tools with no signup, no dark patterns, no BS—that's what developer-friendly looks like. It's not just marketing. It's our identity.

3. SEO (Yes, Also This)

Every developer searching for "base64 decoder" or "jwt decoder online" is a potential customer who might also need a URL shortener. The tools get traffic, the traffic discovers our main product.

It's a legitimate marketing play. But the difference is: we built tools we actually use. Not half-baked "sign up to see results" garbage.

The Full List

Encoding & Decoding

Tool	URL	What It Does
Base64 Encoder/Decoder	/u/b64	Encode/decode Base64 strings
URL Encoder/Decoder	/u/encode	Encode/decode URL components
JWT Decoder	/u/jwt	Decode and inspect JSON Web Tokens

JWT Decoder is our most-used tool. Paste a token, instantly see the header, payload, and expiration time. No external requests—everything happens in your browser.

Generators

Tool	URL	What It Does
Password Generator	/u/pwd	Generate secure passwords with strength meter
UUID Generator	/u/uuid	Generate v1, v4, and v7 UUIDs
Random Generator	/u/random	Generate random strings, numbers, UUIDs
Hash Generator	/u/hash	Generate MD5, SHA-1, SHA-256, SHA-512 hashes
Lorem Ipsum Generator	/u/lorem	Generate placeholder text
QR Code Generator	/u/qr	Create QR codes with custom colors and sizes

Password Generator calculates actual entropy, not fake "strength bars." A 12-character password with all character types = ~79 bits of entropy. We show the math.

Text Tools

Tool	URL	What It Does
JSON Formatter	/u/json	Format, validate, beautify JSON
Markdown Preview	/u/md	Write and preview markdown in real-time
Diff Checker	/u/diff	Compare two texts, supports JSON/YAML
Text Case Converter	/u/case	Convert between UPPER, lower, camelCase, snake_case
Word Counter	/u/words	Count words, characters, sentences, reading time
URL Slug Generator	/u/slug	Convert text to clean, SEO-friendly slugs

Diff Checker is surprisingly powerful. It auto-detects JSON/YAML and formats before comparing, so you can paste minified JSON and still get a readable diff.

Converters

Tool	URL	What It Does
Color Converter	/u/color	Convert between HEX, RGB, HSL, HSV
Unix Timestamp Converter	/u/time	Convert timestamps to human dates and back

Unix Timestamp Converter handles milliseconds vs seconds automatically. No more "is this 10 digits or 13?" confusion.

URL & Marketing Tools

Tool	URL	What It Does
UTM Builder	/u/utm	Build URLs with UTM parameters for campaign tracking
URL Checker	/u/check	Check DNS, SSL, redirects, and safety status
OG Preview	/u/og	Preview how URLs appear on social media

UTM Builder ties directly into our URL shortener. Build your UTM link, optionally shorten it, track everything. Full funnel in one page.

Design Philosophy

1. Client-Side First

Most tools run entirely in your browser. No server requests. No data sent anywhere. When you paste a JWT, it never leaves your machine.

The only tools that require API calls:

URL Checker (needs to fetch the actual URL)
OG Preview (needs to fetch metadata)

And even those are rate-limited and don't store anything.

2. No Dark Patterns

No "sign up to see results"
No "share to unlock"
No interstitial ads
No newsletter popups
No fake urgency

You land on the page, use the tool, leave. That's it.

3. Keyboard-First

Every tool supports:

Ctrl/Cmd + Enter to execute
Ctrl/Cmd + C to copy result
Esc to clear

We use these tools daily. Keyboard shortcuts matter.

4. Mobile-Responsive

All tools work on mobile. The text areas resize. The buttons are tap-friendly. You can decode a JWT on your phone at 2 AM when production is on fire.

Not that we've ever done that.

The Tech Stack

React + TypeScript + Tailwind CSS
├── Client-side crypto for hashes
├── Client-side JWT parsing
├── Client-side QR generation
├── RTK Query for API calls
└── Shared UI components (shadcn/ui)

Each tool is a standalone page component. No shared state. No complex routing. Load fast, do one thing well.

Usage Stats (The SEO Payoff)

After 3 months:

Tool	Monthly Visits
JWT Decoder	~4,200
JSON Formatter	~3,100
Base64 Encoder	~2,400
Password Generator	~1,800
Others combined	~3,500

Total: ~15,000 monthly visitors who now know jo4.io exists.

Conversion to paid? Low, around 0.3%. But that's 45 paying customers who found us through free tools. At $16/month average, that's $720 MRR from SEO content that costs us nothing to maintain.

Tools We're Still Building

The /u/* pattern works. We're adding more:

Cron Expression Builder - Build and explain cron expressions
Regex Tester - Test regex patterns with live matching
HTTP Header Inspector - See request/response headers for any URL
SVG to PNG Converter - Convert SVG files to raster images

If you have suggestions, let us know.

The Full Directory

Everything lives at jo4.io/u. Bookmark it. Use it. Tell your friends.

Category	Tools
Encoding	Base64, URL Encode, JWT Decode
Generators	Password, UUID, Random, Hash, Lorem, QR
Text	JSON, Markdown, Diff, Case, Word Count, Slug
Converters	Color, Timestamp
Marketing	UTM Builder, URL Checker, OG Preview

20 tools. Zero signup. Zero cost.

What tools do you wish existed? We're always looking for ideas.

Building jo4.io - URL shortener with analytics, plus 20 free developer tools at jo4.io/u.

The Easiest Integration We've Ever Done: Two Markdown Files and a Domain Name Identity Crisis

Anand Rathnas — Sat, 14 Mar 2026 01:34:35 +0000

After wrestling with Zapier OAuth and navigating Pipedream's human-first process, we braced ourselves for ClawHub.

"What hoops will we have to jump through this time?"

The answer: None. Zero hoops. Two markdown files. Done.

The Domain Name Identity Crisis

Before we get into the integration, let's address the elephant in the room.

This platform has had more domain names than I've had hot dinners:

calwd.com → openclaw.ai → clawhub.ai

I'm genuinely not sure what to call it in conversation anymore.

At this point, I half expect to wake up tomorrow and find it's now crabpeople.io.

But here's the thing: the product is actually really good. The domain name musical chairs? Just a startup finding its footing. It happens.

The Integration: Two Files

I'm not exaggerating. The entire Jo4 integration is:

smoothtalk/clawhub/
├── README.md     (33 lines)
└── SKILL.md      (190 lines)

That's it. No OAuth dance. No webhook infrastructure. No SDK to build. Just... markdown.

The README.md

A quick intro for humans:

# Jo4 - URL Shortener & Analytics

🔗 **[jo4.io](https://jo4.io)** - Modern URL shortening with QR codes and detailed analytics.

## Features

- **Short URLs** - Custom aliases, branded links
- **QR Codes** - Auto-generated for every link
- **Analytics** - Clicks, geography, devices, referrers
...

The SKILL.md

This is where the magic happens. It's a markdown file with YAML frontmatter that tells the AI how to use your API:

---
name: jo4
description: URL shortener, QR code generator, and link analytics API
homepage: https://jo4.io
user-invocable: true
metadata:
  openclaw:
    emoji: "🔗"
    primaryEnv: "JO4_API_KEY"
    requires:
      env: ["JO4_API_KEY"]
---

Then you just... document your API. In markdown. With curl examples.

### Create Short URL (Authenticated)

\`\`\`bash
curl -X POST "https://jo4-api.jo4.io/api/v1/protected/url" \
  -H "X-Jo4-API-Key: $JO4_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"longUrl": "https://example.com", "title": "My Link"}'
\`\`\`

The AI reads this, understands the API structure, and can now use it. No code generation. No SDK maintenance. Just documentation that doubles as integration.

Why This Works

ClawHub's approach is beautifully simple:

Documentation IS the integration - If you can document it, it's integrated
Curl examples are universal - Any AI can understand curl -X POST
Environment variables for auth - JO4_API_KEY in the metadata, done
No deployment - Push to their repo, it's live

Compare this to:

Zapier: OAuth implementation, webhook infrastructure, app review, QA queue
Pipedream: GitHub issue, email credentials, component code, QA queue
ClawHub: Write markdown. Push. Done.

The Live Integration

It's already live at clawhub.ai/anandrathnas/jo4.

Users can now ask their AI:

And it just... works. The AI reads the SKILL.md, finds the right endpoint, makes the call.

What We Documented

Section	Purpose
Authentication	How to get and use API keys
Create Short URL	Main endpoint with all parameters
Anonymous URLs	Public endpoint (no auth)
Get URL Details	Retrieve by slug
Get Analytics	Click stats, geo, devices
List URLs	Pagination support
Update/Delete	CRUD operations
QR Codes	Auto-generated URLs
Rate Limits	Plan-based limits
Error Codes	400, 401, 403, 404, 429

All in markdown. All with curl examples. Total effort: maybe 30 minutes.

The Metadata That Makes It Work

The frontmatter is the secret sauce:

metadata:
  openclaw:
    emoji: "🔗"
    primaryEnv: "JO4_API_KEY"
    requires:
      env: ["JO4_API_KEY"]

This tells ClawHub:

Show the 🔗 emoji in the UI
The main credential is JO4_API_KEY
Don't let users invoke without that env var set

No complex OAuth scopes. No token refresh logic. Just "need this env var? yes/no."

Lessons Learned

1. Sometimes Simpler Is Better

After OAuth flows and webhook subscriptions, a markdown file feels almost too easy. But it works. Users get value. That's what matters.

2. Documentation-as-Integration Is Genius

If your docs are good enough for an AI to understand, they're probably good enough for humans too. This forces you to write clear, example-driven documentation.

3. Domain Names Are Just Names

Calwd. OpenClaw. ClawHub. Who cares? The product works. The integration was painless. I'll update my bookmarks as needed.

Integration Complexity Comparison

Platform	Time	Files/Code	Auth	Process
Zapier	1 week	OAuth server + REST Hooks	OAuth 2.0 + PKCE	Review queue
Pipedream	4 days	OAuth + Components	OAuth 2.0 + PKCE	Email + QA
ClawHub	30 min	2 markdown files	API Key env var	Push and done

The Future-Proofing Question

"What if they change the domain again?"

Honestly? I'll update the bookmark. The integration itself won't break—it's just markdown files in a repo.

"What if they rename the whole product?"

Then I'll have another blog post to write. Content calendar wins either way.

Try It Yourself

If you have a REST API with decent documentation, you can probably integrate with ClawHub in an afternoon:

Create a SKILL.md with frontmatter
Document your endpoints with curl examples
Specify required env vars in metadata
Push to their repo
Done

No OAuth implementation. No webhook infrastructure. No SDK maintenance.

Sometimes the best integrations are the ones that don't feel like integrations at all.

What's the easiest integration you've ever done? And have you noticed any other products with domain name identity issues?

Building jo4.io - URL shortener with analytics. Now available on ClawHub... whatever they call it next week.

Getting Your App on Pipedream: No Dashboard, Just Humans (And That's Actually Great)

Anand Rathnas — Wed, 11 Mar 2026 01:34:43 +0000

After getting our Zapier OAuth integration working, we figured Pipedream would be similar. Build the OAuth endpoints, submit the app, wait for approval.

We were half right.

The Plot Twist: No Developer Dashboard

Zapier has a developer platform where you:

Create an app
Configure OAuth settings
Upload your client ID/secret
Submit for review

Pipedream? None of that.

There's no developer dashboard. No self-service portal. No "Create New App" button.

Instead, you open a GitHub issue.

"Wait, what?"

The Process (It's Actually Fast)

Step 1: Open a GitHub Issue

I created issue #19728 with:

App name and description
Link to API documentation
OAuth endpoints
Triggers and actions I wanted to build
Note that I had component code ready

**OAuth 2.0 Details:**
- Authorization URL: https://jo4-api.jo4.io/oauth/authorize
- Token URL: https://jo4-api.jo4.io/oauth/token
- PKCE Support: Yes (required, S256)
- Scopes: read, write

I have the complete component code ready and can submit PR
once OAuth App ID is provided.

Step 2: Human Responds (Same Day!)

Within hours, someone from the Pipedream integrations team replied asking how they could get OAuth 2.0 credentials to start integrating.

No ticket queue. No "we'll get back to you in 3-5 business days." A real person, asking a real question.

Step 3: Exchange Credentials via Email

Here's where it gets interesting. They asked me to email the OAuth client credentials directly to a team member.

No secure portal. No encrypted upload form. Just... email.

Is this concerning? Maybe. But here's the thing: these credentials are specific to Pipedream's redirect URI. They can't be used anywhere else. And the speed of a direct email beats waiting for a ticket system.

Tip I shared with them:

They're probably working on it. But honestly? The current process worked fine.

Step 4: App Submitted for QA

Four days after opening the issue, they confirmed the Jo4 app was submitted for QA as an OAuth 2.0 app.

That's it. From GitHub issue to QA queue in under a week.

The Wait (Current Status)

As of writing, the app is "awaiting QA." When I tried to access the app link, I got a 404:

I asked if the 404 was expected. It was — the app isn't released until it clears QA.

Fair enough. The QA process takes time. But the human interaction throughout has been stellar.

What We Reused from Zapier

The beautiful part: we didn't write new OAuth code.

Our Zapier integration required:

OAuth 2.0 Authorization Code flow
Mandatory PKCE (S256)
Token refresh support
Proper error responses

Pipedream needs... exactly the same thing.

Same endpoints:
  /oauth/authorize
  /oauth/token
  /oauth/userinfo

Same PKCE requirement:
  code_challenge_method: S256

Same token format:
  { access_token, refresh_token, expires_in, scope }

The only difference was creating a new OAuth client with Pipedream's redirect URI:

https://api.pipedream.com/connect/oauth/oa_XXXXX/callback

Everything else? Already done.

The Triggers and Actions

What we're shipping:

Type	Name	Description
Trigger	New URL Created	Webhook fires when user creates a short URL
Trigger	New Referrer Domain	Webhook fires when link gets traffic from new source
Action	Create Short URL	Create with optional custom slug
Action	Get URL Details	Retrieve URL by slug
Action	List URLs	Paginated list of all URLs

Same as Zapier. Same webhook infrastructure. Same REST Hook pattern (subscribe/unsubscribe).

Why Human-First Integration Is Actually Better

I've submitted apps to various platforms. Here's the typical experience:

Fill out 47 form fields
Upload screenshots in specific dimensions
Wait 2 weeks for automated rejection
Resubmit with minor changes
Wait another 2 weeks
Repeat

Pipedream's approach:

Open issue with relevant details
Human asks clarifying questions
Email credentials
App in QA within a week

The human touch catches edge cases faster. Their team noticed I mentioned API keys require an upgrade on our free tier and asked specifically about OAuth credentials. A form wouldn't have caught that nuance.

Timeline Summary

Date	Event
Jan 19	Opened GitHub issue
Jan 19	Pipedream team responds (same day)
Jan 21	Credentials exchanged via email
Jan 23	App submitted for QA
Jan 30	Follow-up—still awaiting QA
Now	Waiting for release

Total time from "I want to integrate with Pipedream" to "app in QA": 4 days.

Lessons Learned

1. OAuth Investment Pays Dividends

The three days we spent getting OAuth right for Zapier? Zero additional work for Pipedream. Same endpoints, same PKCE, same token format.

2. Human Support > Automated Portals (Sometimes)

For small-to-medium apps, direct human contact is faster. Their team answered questions I didn't know I had.

3. Document Everything in the Issue

The more context you provide upfront, the fewer back-and-forth messages. I included:

Full OAuth spec
Available scopes
Trigger/action descriptions
Link to Swagger docs

4. Be Patient with QA

The integration team is fast. QA takes time. That's okay—they're protecting their users.

What's Next

Once the app clears QA, we'll:

Submit the PR with component code
Test the full flow end-to-end
Write documentation
Announce the integration

We'll update this post when it's live.

Have you integrated with Pipedream? What was your experience with their process?

Building jo4.io - URL shortener with analytics. Soon available on Pipedream alongside Zapier.

The 5 Edge Cases That Broke Our Dev.to Auto-Crossposting (And How We Fixed Them)

Anand Rathnas — Sun, 08 Mar 2026 01:34:38 +0000

In our previous post, we covered the producer-consumer problem for blog scheduling. But we glossed over the crossposting part.

"Just POST to the dev.to API," we said. "How hard could it be?"

Narrator: It was hard.

The Setup

We have a Node.js script that runs daily via GitHub Actions:

// Simplified flow
1. Find all markdown posts with publishAfter <= today
2. Check if they exist on dev.to already
3. If not, create them
4. Send Slack notification

Sounds straightforward. Here are the edge cases that broke it.

Edge Case 1: How Do You Know If a Post Already Exists?

The Problem

We can't just check our local database—we don't have one. The blog is a static site. So how do we avoid posting duplicates?

Naive approach: Keep a .crossposted.json file locally.

Why it fails: Someone manually posts to dev.to. Someone deletes the JSON file. Someone runs the script from a different machine. Duplicates everywhere.

The Fix: dev.to Is the Source of Truth

async fetchDevtoArticles() {
  const response = await fetch(`${DEVTO_API_URL}/me/published?per_page=100`, {
    headers: { 'api-key': this.apiKey },
  });

  const articles = await response.json();

  // Store by canonical_url for O(1) lookup
  for (const article of articles) {
    if (article.canonical_url) {
      this.devtoArticles.set(article.canonical_url, {
        id: article.id,
        url: article.url,
        title: article.title,
      });
    }
  }
}

Before creating anything, we fetch ALL our existing dev.to articles. The canonical_url field is unique—it's the original source URL. If our canonical URL already exists, skip.

Bonus: dev.to returns a 422 error with "canonical" in the message if you try to create a duplicate. We catch that too:

if (response.status === 422 && errorText.toLowerCase().includes('canonical')) {
  return { duplicate: true, title: frontmatter.title };
}

Belt and suspenders.

Edge Case 2: The 60-Day Time Bomb

The Problem

Our script only looks back 60 days on dev.to (performance optimization—we don't need articles from 2 years ago). But what happens to a post with publishAfter: "2025-01-01" that we never crossposted?

Scenario:

January: Write a post, set publishAfter: "2025-01-15"
January 15: Script runs, posts to dev.to ✅
March 20: 65 days later, the script's dev.to lookback window no longer includes this article
Some bug causes the post to be re-processed
Duplicate post on dev.to ❌

The Fix: Auto-Update Stale Dates

If a post has publishAfter older than 60 days, we automatically update it to today:

if (this.isOlderThanDevtoMaxDays(publishAfter)) {
  console.log(`[publish-after] "${title}" has old publishAfter (${publishAfter}), updating to ${today}`);
  return { shouldProcess: true, needsDateUpdate: true, newDate: today };
}

And here's the edge case's edge case—we need to commit this change to git:

// After processing all posts
if (this.filesToCommit.length > 0 && !this.dryRun) {
  commitChanges(this.filesToCommit, 'chore: auto-update old publishAfter dates to today');
}

function commitChanges(files, message) {
  for (const file of files) {
    execSync(`git add "${file}"`, { stdio: 'pipe' });
  }
  execSync(`git commit -m "${message}"`, { stdio: 'pipe' });
}

Why commit? Because if the script runs again before you pull, it would try to update the same posts again. The commit ensures the updated dates persist.

Slack notification: "⚠️ publishAfter updated to today for "My Post" - please pull latest"

Edge Case 3: Accidental Content Overwrites

The Problem

You crosspost a blog post. A week later, you fix a typo locally. The script runs. Does it update dev.to?

If yes: What if you intentionally made dev.to-specific edits? Gone.
If no: How do you push updates when you actually want them?

The Fix: Explicit Update Intent

Updates only happen when you set updatedAt in frontmatter:

---
title: "My Post"
publishAfter: "2026-02-15"
updatedAt: "2026-02-20"  # <-- This triggers the update
---

if (existingArticle) {
  if (frontmatter.updatedAt) {
    // Explicit intent to update - proceed
    result = await this.updateArticle(existingArticle.id, frontmatter, body);
  } else {
    // No updatedAt = skip (don't accidentally overwrite)
    console.log(`[exists] ${frontmatter.title}`);
    continue;
  }
}

No updatedAt? No update. Simple opt-in.

Edge Case 4: dev.to Rate Limiting

The Problem

dev.to allows 10 requests per 30 seconds. Try to crosspost 15 articles at once and you'll hit 429s.

The Fix: Delay + Retry with Backoff

// After each successful post
await new Promise(resolve => setTimeout(resolve, 3500)); // 3.5s delay

// On rate limit (429)
if (response.status === 429 && retryCount < CONFIG.maxRetries) {
  const retryAfter = parseInt(response.headers.get('retry-after'), 10) || 60;
  console.log(`[rate-limited] Waiting ${retryAfter}s before retry...`);
  await new Promise(r => setTimeout(r, retryAfter * 1000));
  return this.createArticle(frontmatter, body, retryCount + 1);
}

3.5 seconds between posts keeps us under the limit. If we do hit a 429, respect the retry-after header and try again.

Edge Case 5: Partial Failures

The Problem

You have 5 posts to crosspost. Posts 1 and 2 succeed. Post 3 fails (network error). What happens to posts 4 and 5?

The Fix: Continue on Failure + Report All

for (const file of files) {
  try {
    result = await this.createArticle(frontmatter, body);
    results.push({ action: 'created', title: frontmatter.title, url: result.url });
    await notifySlack(`Crossposted to dev.to: ${title} → ${result.url}`);
  } catch (error) {
    console.error(`[failed] ${frontmatter.title}: ${error.message}`);
    results.push({ action: 'failed', title: frontmatter.title, error: error.message });
    await notifySlack(`Failed to crosspost "${title}": ${error.message}`, true);
    // Continue to next post - don't abort
  }
}

// Exit with error code if any failures
if (failed > 0) {
  process.exit(1);
}

Every post gets attempted. Every result gets recorded. Every failure gets Slacked. The exit code tells CI whether to retry.

The Complete Slack Notification System

Here's every scenario that triggers a notification:

Event	Emoji	Message
New crosspost	✅	`Crossposted to dev.to: {title} → {url}`
Updated post	✅	`Updated on dev.to: {title} → {url}`
Date auto-fixed	⚠️	`publishAfter updated to today for "{title}" - please pull latest`
Duplicate found	⚠️	`Duplicate on dev.to for "{title}" - already exists, skipping`
Failure	⚠️	`Failed to crosspost "{title}": {error}`

Slack Integration

One environment variable:

export SLACK_JO4_BLOGS_WH="https://hooks.slack.com/services/T00/B00/XXX"

That's it. The script handles the rest:

async function notifySlack(message, isWarning = false) {
  if (!CONFIG.slackWebhook) {
    console.log(`[slack-skip] ${message}`);
    return;
  }

  const emoji = isWarning ? '⚠️' : '✅';
  const text = `${emoji} *Jo4 Blog*: ${message}`;

  await fetch(CONFIG.slackWebhook, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text }),
  });
}

No Slack webhook configured? It logs to console instead. Graceful degradation.

Configuration Knobs

const CONFIG = {
  localMaxDays: parseInt(process.env.LOCAL_MAX_DAYS, 10) || 30,
  devtoMaxDays: parseInt(process.env.DEVTO_MAX_DAYS, 10) || 60,
  maxRetries: 3,
  slackWebhook: process.env.SLACK_JO4_BLOGS_WH,
};

Variable	Default	Purpose
`LOCAL_MAX_DAYS`	30	Only process posts from last X days (unless `publishAfter` is set)
`DEVTO_MAX_DAYS`	60	How far back to check dev.to for existing articles
`SLACK_JO4_BLOGS_WH`	-	Slack webhook URL
`DEVTO_API_KEY`	-	Your dev.to API key (required)

The Full Algorithm

1. Fetch all our articles from dev.to (last 60 days)
   → Store by canonical_url for O(1) lookup

2. For each local markdown file:
   a. Skip if draft or crosspost: false
   b. Skip if publishAfter > today (scheduled for future)
   c. If publishAfter is older than 60 days:
      → Update publishAfter to today
      → Queue file for git commit
      → Slack warning
   d. Check if canonical_url exists on dev.to:
      → If yes AND updatedAt is set: UPDATE
      → If yes AND no updatedAt: SKIP
      → If no: CREATE
   e. Wait 3.5 seconds (rate limiting)
   f. On 429: retry with backoff

3. Commit any auto-updated files to git

4. Report summary + exit code

Lessons Learned

Use the destination as source of truth - Don't maintain local state for external systems
Explicit > implicit - Updates require updatedAt flag, no accidental overwrites
Edge cases have edge cases - Old dates need auto-fixing, auto-fixes need git commits
Fail gracefully - Continue on error, report everything, use exit codes for CI
Integrate Slack early - One webhook URL, five notification scenarios, zero config UI

What edge cases have you hit with crossposting? Every automation has that one bug that only shows up at 3 AM.

Building jo4.io - URL shortener with analytics. Our blog auto-crossposts to dev.to using exactly this system.

5 Hard Lessons from Implementing Zapier OAuth in Spring Boot

Anand Rathnas — Thu, 05 Mar 2026 01:35:06 +0000

Three days. That's how long it took to get a "simple" OAuth integration working with Zapier. The docs made it look easy. Reality had other plans.

Here's what I learned building OAuth 2.0 with PKCE for jo4.io - a URL shortener that now integrates with Zapier, Make.com, and n8n.

Lesson 1: Your OAuth Tokens Fight Your JWT Tokens

Spring Security's filter chain doesn't know the difference between your OAuth access tokens and Auth0's JWTs. Both arrive as Authorization: Bearer <token>. Chaos ensues.

The Problem

OAuth token authentication successful: userId=2, clientId=zapier
...
BearerTokenAuthenticationFilter: Failed to authenticate: Invalid JWT

Wait, what? We just authenticated successfully. Why is it failing?

The JWT filter runs after our OAuth filter and tries to re-validate the same token as a JWT. It fails (obviously - it's not a JWT), and returns 401.

The Fix

Strip the Authorization header after successful OAuth authentication:

@Override
protected void doFilterInternal(HttpServletRequest request,
        HttpServletResponse response, FilterChain filterChain) {

    String token = extractBearerToken(request);

    // Skip if this looks like a JWT (has 3 base64 parts with "alg" header)
    if (isJwtToken(token)) {
        filterChain.doFilter(request, response);
        return;
    }

    try {
        OAuthService.ValidatedToken validated = oauthService.validateAccessToken(token);
        SecurityContextHolder.getContext().setAuthentication(
            new OAuthTokenAuthentication(validated.getUser(), validated.getToken())
        );

        // CRITICAL: Strip header so JWT filter doesn't try to re-validate
        filterChain.doFilter(new AuthorizationStrippingRequestWrapper(request), response);

    } catch (Exception e) {
        sendErrorResponse(response, HttpStatus.UNAUTHORIZED, "invalid_token",
            "The access token is invalid, expired, or revoked");
    }
}

Key insight: Filter chain order matters. Your OAuth filter runs, authenticates, then passes to the next filter. If that next filter sees a Bearer token, it'll try to process it again.

Lesson 2: Concurrent Token Refresh = Race Condition Hell

Zapier's backend makes parallel requests. When a token expires, multiple workers hit your refresh endpoint simultaneously.

The Problem

Thread-1: Refresh token, create new access token A
Thread-1: Revoke old access token (standard practice, right?)
Thread-2: Refresh token, create new access token B
Thread-2: Revoke old access token... wait, that's token A that Thread-1 just created

User sees: "This account is expired. Please reconnect it."

The (Counter-Intuitive) Fix

Don't revoke access tokens on refresh. Let them expire naturally.

public TokenResponse refreshAccessToken(String refreshToken) {
    OAuthRefreshTokenEntity refresh = validateRefreshToken(refreshToken);

    // Create new access token
    String newAccessToken = generateAccessToken();
    saveAccessToken(newAccessToken, refresh.getUserId(), refresh.getClientId());

    // NOTE: We intentionally do NOT revoke old access tokens.
    // This prevents race conditions when multiple concurrent refresh
    // requests would revoke each other's newly created tokens.
    // Access tokens have short lifetimes (1 hour) and expire naturally.

    return new TokenResponse(newAccessToken, refresh.getToken(), 3600);
}

This is standard OAuth 2.0 practice. Access tokens are short-lived by design. Revoking them on refresh is "clever" but breaks under concurrency.

Lesson 3: PKCE Validation Must Be Explicit

@NotBlank on your DTO doesn't always trigger. Bean validation has quirks.

The Problem

Our request DTO:

public record AuthorizeConsentRequest(
    @NotBlank String clientId,
    @NotBlank String redirectUri,
    String scope,
    @NotBlank(message = "PKCE code_challenge is required") String codeChallenge,
    String codeChallengeMethod
) {}

But requests without codeChallenge were getting through. The security bug: attackers could bypass PKCE entirely.

The Fix

Defense in depth - validate explicitly:

@PostMapping("/authorize")
public ResponseEntity<?> authorizeConsent(@Valid @RequestBody AuthorizeConsentRequest request) {

    // SECURITY: Explicit PKCE validation (defense-in-depth)
    if (request.codeChallenge() == null || request.codeChallenge().isBlank()) {
        return errorResponse("invalid_request",
            "PKCE code_challenge is required per OAuth 2.1 security requirements");
    }

    // ... rest of authorization logic
}

Rule: Security validations should be explicit in code, not just annotations.

Lesson 4: Zapier Has Specific Token Response Requirements

The OAuth spec is flexible. Zapier is not.

Requirements I Discovered the Hard Way

Requirement	What I Did Wrong	What Zapier Needs
Token location	Nested in `data` object	Top-level JSON keys
Content-Type	`application/json; charset=UTF-8`	`application/json` works, but verify
`scope` field	Omitted (optional per spec)	Must be present
`token_type`	Returned `Bearer`	Must be exactly `Bearer` (case-sensitive)

Correct response format:

{
  "access_token": "jo4_at_abc123...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "jo4_rt_xyz789...",
  "scope": "read write"
}

Lesson 5: E2E Tests Are Worth the Investment

After two days of "try it and see" debugging, I wrote comprehensive E2E tests. Found three bugs in 10 minutes.

The Concurrent Refresh Test That Found the Race Condition

@Test
void step9_concurrentRefreshDoesNotCauseRaceCondition() throws Exception {
    int concurrentRequests = 5;
    ExecutorService executor = Executors.newFixedThreadPool(concurrentRequests);
    List<Future<ResponseEntity<String>>> futures = new ArrayList<>();

    // Fire 5 refresh requests simultaneously
    for (int i = 0; i < concurrentRequests; i++) {
        futures.add(executor.submit(() -> {
            MultiValueMap<String, String> params = new LinkedMultiValueMap<>();
            params.add("grant_type", "refresh_token");
            params.add("refresh_token", refreshToken);
            params.add("client_id", testClientId);
            params.add("client_secret", testClientSecret);

            return restTemplate.postForEntity("/oauth/token",
                new HttpEntity<>(params, formHeaders), String.class);
        }));
    }

    // ALL must succeed
    for (Future<ResponseEntity<String>> future : futures) {
        ResponseEntity<String> response = future.get(10, TimeUnit.SECONDS);
        assertThat(response.getStatusCode().is2xxSuccessful()).isTrue();
    }
}

This test would have caught the race condition immediately.

TL;DR

Strip Authorization header after OAuth auth succeeds - prevents JWT filter conflicts
Don't revoke tokens on refresh - causes race conditions under concurrent requests
Validate PKCE explicitly - don't trust annotations alone for security
Match Zapier's exact format - tokens at top level, scope included
Write E2E tests first - 10 minutes of tests beats 2 days of production debugging

OAuth looks simple in diagrams. The edge cases will humble you.

What OAuth integration horror stories do you have? I'd love to hear I'm not alone.

Building jo4.io - URL shortener with Zapier, Make.com, and n8n integrations.

How We Solved the Producer-Consumer Problem (For Blog Posts)

Anand Rathnas — Mon, 02 Mar 2026 01:35:15 +0000

You know the producer-consumer problem from computer science, right? One process creates stuff, another process consumes it, and if they're not synchronized, chaos ensues.

Turns out, content creation has the exact same problem.

The Problem: Bursty Writers, Consistent Readers

Here's how blog writing actually works:

Producer (Me):

Monday: Write 4 posts in a caffeine-fueled frenzy
Tuesday-Sunday: *crickets*
Next Monday: Panic, write 3 more posts

Consumer (Readers & SEO):

Expectation: Consistent 3x/week publishing
Reality: 4 posts on Monday, nothing for 2 weeks, then 7 posts on a random Tuesday

Google hates inconsistency. Readers forget you exist. Your newsletter goes from "weekly insights" to "occasional ramblings from someone who may or may not still be alive."

Classic producer-consumer mismatch.

The Traditional Solutions (That Don't Work)

1. "Just Be Consistent"

Ah yes, the "just don't have ADHD" approach. Revolutionary.

The problem isn't motivation—it's that creative energy comes in bursts. Some days you write 3,000 words before breakfast. Other days, you stare at a blank screen and contemplate becoming a goat farmer.

2. Use a CMS with Scheduling

WordPress, Ghost, and others have scheduling. But they require:

Manual date picking for each post
Remembering what you've already scheduled
A calendar that doesn't sync with your actual life
Discipline (see point #1)

3. Hire a Content Manager

laughs in solo developer budget

Our Solution: Stock-Based Scheduling

We built a simple system with one core idea: treat blog posts like inventory.

The Stock File

{
  "_articleStockWouldLastUpto": "2026-02-26",
  "getting-started-with-jo4": "2026-01-31",
  "api-first-url-shortener": "2026-02-03",
  "claude-code-hooks": "2026-02-05",
  "elasticache-vs-memorydb": "2026-02-07"
}

Each post gets a publishAfter date in its frontmatter. The stock.json file tracks everything:

What's scheduled
When each post goes live
When you'll run out of content

That last field—_articleStockWouldLastUpto—is the magic. It's your inventory level.

The Workflow

When I write (producer):

Create post with content
Set publishAfter to the next available slot
Update stock.json with the new entry
Update _articleStockWouldLastUpto if this is the latest

When GitHub Actions runs (consumer):

Check which posts have publishAfter <= today
Build and publish those posts
Crosspost to dev.to
Check stock levels

The Low Stock Warning

Here's the clever bit. Every day at 1 AM UTC, our CI pipeline checks:

STOCK_DATE=$(jq -r '._articleStockWouldLastUpto' stock.json)
DAYS_LEFT=$(( (STOCK_EPOCH - TODAY_EPOCH) / 86400 ))

if [ "$DAYS_LEFT" -lt 3 ]; then
  echo "LOW STOCK! Only $DAYS_LEFT days remaining!"
  # Send Slack notification
fi

If I have less than 3 days of content queued up, I get a Slack message:

It's like a grocery store inventory system, but for words.

Why This Works

1. Decouples Writing from Publishing

I can write 5 posts on a Sunday afternoon and not worry about when they'll go live. The system handles the "when," I handle the "what."

2. Visualizes the Buffer

Seeing _articleStockWouldLastUpto: "2026-02-26" is motivating. It's concrete. "I have 25 days of content" is way more actionable than "I should probably write more."

3. Prevents Feast-or-Famine

The warning system catches problems before they become crises. No more "oh no, I haven't posted in 3 weeks" panic.

4. Works with Bursts

Write 10 posts in a weekend? Great, you just bought yourself a month. The system doesn't care when you write, just that you eventually do.

The Implementation

Post Frontmatter

---
title: "My Post Title"
description: "SEO-friendly description"
blogPath: my-post-slug
publishAfter: "2026-03-02"
author: Jo4 Team
tags:
  - tag1
  - tag2
  - tag3
  - tag4
---

The publishAfter field is the key. Posts with future dates exist in the repo but aren't built into the public site.

Build Logic

// In 11ty config
eleventyConfig.addCollection("posts", function(collection) {
  const today = new Date().toISOString().split('T')[0];
  return collection
    .getFilteredByGlob("posts/**/index.md")
    .filter(post => post.data.publishAfter <= today)
    .sort((a, b) => b.data.publishAfter.localeCompare(a.data.publishAfter));
});

Future posts are filtered out at build time. Simple.

GitHub Actions Cron

schedule:
  - cron: "0 1 * * *"  # Daily at 1 AM UTC

The pipeline runs daily, checks for newly-eligible posts, builds, deploys, and crossposts.

The Meta Irony

Yes, I'm writing a blog post about automating blog posts.

Yes, this post will be scheduled using the system I'm describing.

Yes, I wrote this during a burst of productivity and it's scheduled 3 weeks out.

The system works.

Lessons Learned

Treat creative work like inventory - Buffers smooth out inconsistency
Automate the boring parts - Date calculation, crossposting, warnings
Make the invisible visible - _articleStockWouldLastUpto turns abstract anxiety into concrete numbers
Design for how you actually work - Bursts are fine if the system handles them

Try It Yourself

The full system is:

11ty for static site generation
GitHub Actions for scheduling and deployment
A simple JSON file for inventory tracking
Slack webhook for low-stock alerts

Total lines of custom code: ~50.

Sometimes the best solutions aren't frameworks or SaaS products. Sometimes it's just a JSON file and a cron job.

How do you handle content scheduling? Built your own system, or using something off-the-shelf?

Building jo4.io - URL shortener with analytics. Yes, we practice what we preach with consistent publishing.

Caching API Responses at the Edge with Cloudflare Cache Rules

Anand Rathnas — Thu, 26 Feb 2026 01:34:49 +0000

Your API is getting hammered. Same endpoints, same responses, thousands of requests. Your origin server is sweating. Here's how I used Cloudflare Cache Rules to serve API responses from the edge—no code changes required.

The Problem

I run a URL shortener. The redirect API (/api/v1/public/a/{shortUrl}) returns JSON with the destination URL. Popular links get hit thousands of times a day.

The thing is—the response rarely changes. A short URL pointing to https://example.com will point there for days, weeks, months. Why hit the origin every single time?

Why Not Just Use Cache-Control Headers?

You could add Cache-Control: public, max-age=3600 in your backend code. But:

Code changes = deployments, testing, potential bugs
Cloudflare doesn't cache API responses by default (even with headers)
Less flexibility—TTLs are baked into code

Cache Rules let you handle this entirely at the infrastructure layer.

The Setup

Cloudflare Dashboard > Caching > Cache Rules > Create Rule

The Expression

(http.request.uri.path contains "/api/v1/public/a/" and not any(http.request.headers["X-Jo4-Url-Key"][*] ne ""))

This matches:

Requests to the short URL API
AND excludes requests with a password header (for protected URLs)

Why exclude password-protected URLs? If you cache them, anyone hitting that URL gets the cached response—including the destination. Security hole.

The Cache Settings

Setting	Value	Why
Cache eligibility	Eligible for cache	Enable caching for matching requests
Edge TTL	2 hours	How long Cloudflare edge holds it
Browser TTL	1 hour	How long the client browser holds it

Why Staggered TTLs?

The 1hr browser + 2hr edge combo is intentional:

0-1hr: Browser serves from local cache (instant, zero network)
1-2hr: Browser cache expired, but Cloudflare edge still has it (fast, no origin)
2hr+: Both expired, request hits origin (fresh data)

This maximizes cache hits while keeping staleness reasonable.

What About Analytics?

Here's the tradeoff: if Cloudflare serves a cached response, your origin never sees the request. No analytics recorded.

For my use case, this is fine. I care about unique visitors, not repeat hits from the same client. The first request hits origin (analytics recorded), subsequent requests get cached.

If you need accurate hit counts:

Use a shorter TTL (15-30 minutes)
Implement client-side analytics beacons
Or just don't cache—sometimes origin load is acceptable

Cache Invalidation

What if a URL changes? Two options:

Wait for TTL (2 hours max in my case—acceptable)
Purge via API:

curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/purge_cache" \
  -H "Authorization: Bearer {api_token}" \
  -H "Content-Type: application/json" \
  --data '{"files":["https://yourdomain.com/api/v1/public/a/abc123"]}'

For most use cases, just pick a TTL you can live with and skip the invalidation complexity.

Bonus: Serve Stale While Revalidating

Enable "Serve stale content while revalidating" in your cache rule. When cache expires:

Cloudflare immediately serves the stale cached response
Simultaneously fetches fresh content from origin
Next request gets the fresh version

Users never wait for origin. Cache stays warm.

Results

Before: Every request hit origin. Popular URLs caused load spikes.

After: ~90% of repeat requests served from edge. Origin load dropped significantly. Response times for cached requests: <50ms globally (served from nearest Cloudflare POP).

Lessons Learned

Cloudflare doesn't cache API responses by default—you need Cache Rules to enable it
Exclude sensitive requests—use expressions to skip password-protected or authenticated endpoints
Stagger your TTLs—browser TTL < edge TTL gives you layered caching
Accept the analytics tradeoff—or implement client-side tracking
Skip invalidation if you can—pick a TTL you can live with, it's simpler
Zero code changes—this is purely infrastructure config

Have questions about edge caching? Drop a comment below.

Building jo4.io - URL shortener with analytics, bio pages, and team workspaces.

Why Your @Async Method Ignores @Transactional (And Leaks Internal Errors)

Anand Rathnas — Tue, 24 Feb 2026 01:35:22 +0000

Production bug report: "Why does the webhook error say 'Executing an update/delete query'?"

That's a JPA internal error. It should never reach users. But there it was, stored in the database and visible in the admin panel. Here's how an innocent-looking @Async method broke everything.

The Code That Looked Fine

@Slf4j
@Service
@RequiredArgsConstructor
public class WebhookService {

    private final WebhookRepository webhookRepository;
    private final WebhookEventRepository webhookEventRepository;

    @Async
    public void fireEvent(Long userId, String event, Map<String, Object> payload) {
        List<WebhookEntity> webhooks = webhookRepository
            .findByUserIdAndEnabledTrue(userId);

        for (WebhookEntity webhook : webhooks) {
            WebhookEventEntity webhookEvent = createWebhookEvent(webhook, event, payload);
            deliverWebhook(webhookEvent, webhook);
        }
    }

    @Transactional
    public void deliverWebhook(WebhookEventEntity event, WebhookEntity webhook) {
        // ... send HTTP request ...

        if (success) {
            event.setStatus(WebhookEventStatus.DELIVERED);
            webhookEventRepository.save(event);

            // Reset failure count atomically
            webhookRepository.resetFailureCount(webhook.getId(), System.currentTimeMillis());
        }
    }
}

The repository method:

@Modifying
@Query("UPDATE WebhookEntity w SET w.failureCount = 0, w.modifiedTime = :now WHERE w.id = :id")
void resetFailureCount(@Param("id") Long id, @Param("now") Long now);

Looks reasonable, right? @Async for background processing, @Transactional for database consistency, @Modifying for atomic updates.

The Error

javax.persistence.TransactionRequiredException:
Executing an update/delete query

This was getting stored in the lastError field of webhook events. Users could see it. Security and UX nightmare.

The Root Cause: Self-Invocation Bypasses Proxies

Spring's @Transactional works through proxies. When you call a @Transactional method, you're actually calling a proxy that:

Starts a transaction
Calls your actual method
Commits or rolls back

But here's the catch: self-invocation bypasses the proxy.

@Async
public void fireEvent(...) {
    // This runs in a new thread, outside any transaction

    for (WebhookEntity webhook : webhooks) {
        // This calls the method DIRECTLY, not through the proxy
        deliverWebhook(webhookEvent, webhook);  // @Transactional is ignored!
    }
}

When fireEvent() calls deliverWebhook(), it's calling this.deliverWebhook() - the actual method on the instance, not the Spring proxy. The @Transactional annotation is invisible.

The @Modifying query requires an active transaction. No transaction = exception.

The Fix: TransactionTemplate

When you can't rely on @Transactional, use programmatic transaction management:

@Slf4j
@Service
@RequiredArgsConstructor
public class WebhookService {

    private final WebhookRepository webhookRepository;
    private final WebhookEventRepository webhookEventRepository;
    private final TransactionTemplate transactionTemplate;  // Inject this

    @Async
    public void fireEvent(Long userId, String event, Map<String, Object> payload) {
        List<WebhookEntity> webhooks = webhookRepository.findByUserIdAndEnabledTrue(userId);

        for (WebhookEntity webhook : webhooks) {
            WebhookEventEntity webhookEvent = createWebhookEvent(webhook, event, payload);
            deliverWebhook(webhookEvent, webhook);
        }
    }

    public void deliverWebhook(WebhookEventEntity event, WebhookEntity webhook) {
        // ... send HTTP request ...

        if (success) {
            // Wrap database operations in explicit transaction
            transactionTemplate.executeWithoutResult(status -> {
                event.setStatus(WebhookEventStatus.DELIVERED);
                webhookEventRepository.save(event);
                webhookRepository.resetFailureCount(webhook.getId(), System.currentTimeMillis());
            });
        }
    }
}

TransactionTemplate doesn't rely on proxies. It explicitly starts and commits transactions. Works everywhere, including:

Self-invoked methods
@Async methods
Lambda callbacks
Anywhere proxy magic fails

Bonus: Sanitize Your Error Messages

Even after fixing the transaction issue, you should never leak internal errors to users:

private String sanitizeErrorMessage(String message) {
    if (message == null) {
        return "Unknown error";
    }

    // Detect internal errors
    if (message.contains("Executing an update/delete query") ||
        message.contains("javax.persistence") ||
        message.contains("org.hibernate") ||
        message.contains("java.sql") ||
        message.contains("SQLException")) {
        log.error("Internal error during webhook delivery: {}", message);
        return "Internal server error";
    }

    return message.length() > 500 ? message.substring(0, 497) + "..." : message;
}

The Debugging Checklist

When you see TransactionRequiredException:

Is the method called from the same class? (self-invocation)
Is the caller @Async? (new thread, no transaction)
Is the method private? (proxies can't intercept)
Is the class final? (no proxy possible)

Any of these = @Transactional won't work. Use TransactionTemplate.

Ever been bitten by Spring proxy magic? What's your go-to solution for transaction issues in async code?

Building jo4.io - a URL shortener that actually handles webhooks reliably.

Implementing Per-Seat Team Billing with Stripe

Anand Rathnas — Sat, 21 Feb 2026 01:34:41 +0000

Adding team plans to a SaaS is tricky. You need per-seat pricing, plan upgrades/downgrades, webhook handling, and graceful degradation when payments fail. Here's how I built it.

The Pricing Model

We offer both individual and team plans:

Individual Plans:

Free:     $0/month     - 30 URLs, 2 bio links, basic analytics
Pro:      $16/month    - 500 URLs, 10 bio links, custom domains
Pro Plus: $48/month    - Unlimited everything, white-label, SSO

Team Plans (per-seat):

Team Pro:      $10/seat/month  - 1,000 URLs/seat, 10 team members max
Team Business: $20/seat/month  - 2,000 URLs/seat, 50 team members, priority support

Annual billing gets 2 months free (pay for 10, get 12).

Creating Checkout Sessions

public String createCheckoutSession(String teamSlug, SubscriptionTier tier,
                                    int seatCount, SubscriptionInterval interval,
                                    Long userId) {
    TeamEntity team = getTeamOrThrow(teamSlug);
    TeamMemberEntity member = getMemberOrThrow(team.getId(), userId);

    // Only owner can manage billing
    if (!member.canManageBilling()) {
        throw new AppException(ErrorCode.TEAM_BILLING_NOT_OWNER);
    }

    // Minimum seats = current active members
    int activeMembers = countActiveFullMembers(team.getId());
    int effectiveSeatCount = Math.max(seatCount, activeMembers);

    String priceId = getPriceIdForTier(tier, interval);

    // Create or get Stripe customer
    String customerId = getOrCreateStripeCustomer(team, member);

    SessionCreateParams params = SessionCreateParams.builder()
        .setCustomer(customerId)
        .setMode(SessionCreateParams.Mode.SUBSCRIPTION)
        .setSuccessUrl(baseUrl + "/teams/" + teamSlug + "/settings?success=true")
        .setCancelUrl(baseUrl + "/teams/" + teamSlug + "/settings?canceled=true")
        .addLineItem(SessionCreateParams.LineItem.builder()
            .setPrice(priceId)
            .setQuantity((long) effectiveSeatCount)
            .build())
        .setSubscriptionData(SessionCreateParams.SubscriptionData.builder()
            .putMetadata("teamId", team.getId().toString())
            .putMetadata("tier", tier.getValue())
            .build())
        .build();

    return Session.create(params).getUrl();
}

The Seat Count Problem

Users will try to downgrade seats below their member count:

int activeMembers = countActiveFullMembers(team.getId());
int effectiveSeatCount = Math.max(seatCount, activeMembers);

If they have 5 team members but try to buy 3 seats, we auto-correct to 5. The UI should warn them first.

Handling Webhooks

Stripe webhooks are the source of truth. Never trust client-side success callbacks.

@PostMapping("/webhooks/stripe")
public ResponseEntity<String> handleWebhook(@RequestBody String payload,
                                            @RequestHeader("Stripe-Signature") String signature) {
    Event event = Webhook.constructEvent(payload, signature, webhookSecret);

    switch (event.getType()) {
        case "checkout.session.completed" -> handleCheckoutCompleted(event);
        case "customer.subscription.updated" -> handleSubscriptionUpdated(event);
        case "customer.subscription.deleted" -> handleSubscriptionCancelled(event);
        case "invoice.payment_failed" -> handlePaymentFailed(event);
    }

    return ResponseEntity.ok("OK");
}

Payment Failed - Pause, Don't Delete

void handlePaymentFailed(Event event) {
    Invoice invoice = (Invoice) event.getDataObjectDeserializer()
        .getObject().orElseThrow();
    String subscriptionId = invoice.getSubscription();

    TeamEntity team = teamRepository.findByStripeSubscriptionId(subscriptionId)
        .orElse(null);
    if (team == null) return;

    // Pause the team - don't delete data
    team.setSubscriptionStatus(SubscriptionStatus.PAST_DUE);
    teamRepository.save(team);

    // Email the owner
    sendPaymentFailedEmail(team);
}

Why pause instead of downgrade immediately? Give users time to fix payment. Nobody wants to lose features because their card expired.

URL Limits Based on Seats

Team URL limits scale with seat count:

private int calculateUrlLimit(String tier, int seatCount) {
    return switch (tier.toUpperCase()) {
        case "TEAM_PRO" -> seatCount * 1000;      // 1,000 URLs per seat
        case "TEAM_BUSINESS" -> seatCount * 2000; // 2,000 URLs per seat
        case "PRO_PLUS" -> Integer.MAX_VALUE;     // Unlimited
        default -> FREE_TEAM_URL_LIMIT;           // Free tier: 100 URLs
    };
}

Billing Portal Access

Let users manage their subscription in Stripe's portal:

public String createBillingPortalSession(String teamSlug, Long userId) {
    TeamEntity team = getTeamOrThrow(teamSlug);

    if (team.getStripeCustomerId() == null) {
        throw new AppException(ErrorCode.TEAM_NO_SUBSCRIPTION);
    }

    SessionCreateParams params = SessionCreateParams.builder()
        .setCustomer(team.getStripeCustomerId())
        .setReturnUrl(baseUrl + "/teams/" + teamSlug + "/settings")
        .build();

    return Session.create(params).getUrl();
}

Testing Webhooks Locally

Use Stripe CLI:

stripe listen --forward-to localhost:8080/api/v1/public/webhooks/stripe

Lessons Learned

Webhooks are truth - Don't trust client-side success callbacks
Pause, don't punish - Give users time to fix payment issues before downgrading
Minimum seats = current members - Prevent invalid states
Email on failures - Users need to know immediately when payment fails
Metadata is your friend - Store teamId and tier in Stripe subscription metadata
Test the cancellation flow - It's the path most likely to have bugs

Building team billing? What edge cases have bitten you?

Building jo4.io - URL shortener with analytics, bio pages, and team workspaces.

Why Auth0 email_verified Was Missing from My Access Token

Anand Rathnas — Thu, 19 Feb 2026 01:35:15 +0000

Spent an hour debugging why verified users were getting blocked. The culprit? Auth0 doesn't include email_verified in access tokens by default.

The Problem

My Spring Boot filter checks if users have verified their email:

Boolean emailVerified = jwt.getClaimAsBoolean("email_verified");
if (emailVerified == null || !emailVerified) {
    response.setStatus(HttpServletResponse.SC_FORBIDDEN);
    response.getWriter().write("{\"error\":\"Email not verified\"}");
    return;
}

Users who had verified their email in Auth0 Dashboard (showing "VERIFIED" badge) were still getting blocked. The logs showed:

User email not verified: sub=auth0|67c6a695657d0f4f7ac8736f

But... they ARE verified. What gives?

The Root Cause

Auth0 includes email_verified in the ID token but NOT in the access token by default.

When you decode your access token, you might see:

{
  "iss": "https://your-tenant.auth0.com/",
  "sub": "auth0|67c6a695657d0f4f7ac8736f",
  "aud": ["https://your-api/"],
  "iat": 1767421775,
  "exp": 1767508175,
  "scope": "openid profile email"
}

No email_verified. Even though you requested the email scope.

The Fix: Auth0 Action

Create a Post-Login Action to add the claim to your access token:

Auth0 Dashboard > Actions > Flows > Login > Add Action

exports.onExecutePostLogin = async (event, api) => {
  // Add email_verified to access token for API validation
  api.accessToken.setCustomClaim('email_verified', event.user.email_verified);
};

Deploy it, drag it into your Login flow.

Now your access token includes:

{
  "email_verified": true,
  "iss": "https://your-tenant.auth0.com/",
  "sub": "auth0|67c6a695657d0f4f7ac8736f",
  ...
}

Why Auth0 Does This

ID tokens are for the client (your frontend) to know who the user is.

Access tokens are for the API (your backend) to authorize requests.

Auth0's philosophy: access tokens should contain authorization info, not identity info. But in practice, your API often needs both.

Alternative: Fetch from Userinfo Endpoint

If you can't modify Auth0 Actions (or want a fallback), fetch from the userinfo endpoint:

// If email_verified not in JWT, fetch from Auth0
if (emailVerified == null) {
    String userinfoUrl = auth0Issuer + "userinfo";
    // GET with Bearer token
    // Parse response for email_verified
}

But this adds latency to every request. The Action approach is better.

OAuth Users Don't Need This Check

Plot twist: if you're using social login (Google, GitHub), the provider already verified the email. Auth0 sets email_verified: true automatically for OAuth users.

You could skip the check for non-database connections:

String subject = jwt.getSubject();
boolean isDatabaseConnection = subject != null && subject.startsWith("auth0|");

if (isDatabaseConnection) {
    // Only check email_verified for username/password users
}

But I prefer keeping it simple - just add the claim via Action and check for everyone. KISS.

The Complete Action

Here's my full Action that also handles resending verification emails:

exports.onExecutePostLogin = async (event, api) => {
  // Always include email_verified in access token
  api.accessToken.setCustomClaim('email_verified', event.user.email_verified);

  // Auto-resend verification email for unverified users (rate limited)
  if (!event.user.email_verified) {
    const lastSent = event.user.user_metadata?.verification_email_last_sent;
    const now = Date.now();
    const ONE_HOUR = 60 * 60 * 1000;

    if (!lastSent || (now - lastSent) > ONE_HOUR) {
      // Trigger verification email via Management API
      // ... (see Auth0 docs for Management API setup)

      api.user.setUserMetadata('verification_email_last_sent', now);
    }
  }
};

Lessons Learned

ID token != Access token - They serve different purposes and contain different claims
Test with actual tokens - Decode your JWT at jwt.io to see what's really there
Actions are powerful - You can add any claim you need to the access token
Check Auth0 Dashboard carefully - Just because it shows "VERIFIED" doesn't mean the token has the claim

Ever been burned by missing JWT claims? What other claims do you add via Actions?

Building jo4.io - a URL shortener with analytics, bio pages, and white-labeling.

Cloudflare Bot Fight Mode Breaks Zapier OAuth (And How to Fix It)

Anand Rathnas — Tue, 17 Feb 2026 01:35:14 +0000

This is a follow-up to my previous article on implementing Zapier OAuth in Spring Boot. After solving all the code issues, I hit one more wall.

You've implemented OAuth 2.0 with PKCE. Your E2E tests pass. You deploy to production. Zapier shows:

Oh, foo. Zapier could not connect to your account.
Try connecting again. Or go to your Zaps and try re-enabling them.

The Cloudflare "Just a moment..." page strikes again.

The Symptom

Zapier's OAuth callback hits your /oauth/token endpoint and gets a 403 with an HTML page instead of JSON:

<!DOCTYPE html>
<html lang="en-US">
<head><title>Just a moment...</title>
<!-- Cloudflare challenge page -->

Your logs show nothing. Because the request never reaches your application.

The Root Cause: Bot Fight Mode

If you have Bot Fight Mode enabled in Cloudflare (Security > Settings > Bot traffic), it's challenging Zapier's automated requests. Even though Zapier is in Cloudflare's verified bots list.

"Easy fix," I thought. "I'll create a WAF rule to skip Bot Fight Mode for /oauth/* paths."

Wrong.

The Documented Limitation You Won't Find Easily

From Cloudflare's official docs:

And the explanation:

Translation: Bot Fight Mode (Free plan) runs outside the normal rule engine. No WAF rule, Page Rule, or IP Access Rule can bypass it for specific paths. It's all-or-nothing.

The Solutions

Option 1: Disable Bot Fight Mode Entirely (Free Plan)

If you're on Cloudflare Free:

Go to Security > Settings
Click Bot traffic filter
Turn off Bot Fight Mode

Your OAuth works. But you lose bot protection everywhere.

Option 2: Upgrade to Pro ($20/month) and Use Super Bot Fight Mode

Super Bot Fight Mode does run in the Ruleset Engine. You can skip it for specific paths.

Step 1: Enable Super Bot Fight Mode

Upgrade to Cloudflare Pro
Go to Security > Settings > Bot traffic
Configure Super Bot Fight Mode:
- Definitely automated traffic: Block or Managed Challenge
- Verified bots: Allow

Step 2: Create Skip Rule for OAuth

Go to Security > Security rules
Click Create rule

Configure:

Rule name: Skip SBFM for OAuth
Expression:

 (starts_with(http.request.uri.path, "/oauth/token")) or
 (starts_with(http.request.uri.path, "/oauth/authorize")) or
 (starts_with(http.request.uri.path, "/oauth/userinfo"))

Action: Skip
WAF components to skip: Check All Super Bot Fight Mode Rules
1. Click Deploy

Step 3: Test Zapier

Retry the OAuth connection. Should work now.

Why This Matters

Plan	Bot Protection	Can Skip for APIs?
Free	Bot Fight Mode	No
Pro ($20/mo)	Super Bot Fight Mode	Yes

If you're building integrations with Zapier, Make.com, n8n, or any other automation platform, you need the ability to exempt your OAuth endpoints from bot challenges. That requires Pro.

The Cost-Benefit

$20/month for Cloudflare Pro gives you:

Super Bot Fight Mode with path-based exceptions
Better analytics
Polish Rules (5 vs 0)
Faster support

For a production SaaS with third-party integrations, it's worth it. The alternative is no bot protection at all.

TL;DR

Bot Fight Mode (Free): Cannot be bypassed for specific paths. All or nothing.
Super Bot Fight Mode (Pro): Can be skipped using WAF custom rules.
The fix: Upgrade to Pro, enable SBFM, create Skip rule for /oauth/* paths.

OAuth integration isn't done until Cloudflare lets the requests through.

Building jo4.io - URL shortener with Zapier, Make.com, and n8n integrations.