Documentation
Product usage from PostHog
How much each person uses your product, read from PostHog.
If you already run PostHog, you already know who uses your product and how much. Kicklace reads two things out of it and leaves the rest.
A summary on each person. For everybody PostHog has seen with an email address: when they were first and last seen, and how many events they fired in the last 30 days and the last 7. Three figures on their record, kept up to date every hour. That's what makes "quiet for a month" answerable about a person rather than a chart.
The events that count. The few you name, like "project created" or "design exported", land on that person's timeline, so a stage or a side road on your Lifecycle map can start from one.
Not everything else. Everything you didn't name is counted into the figures above and thrown away. PostHog keeps your analytics; Kicklace keeps your customers.
Four things it never does.
- It never writes to PostHog. Every call is a read.
- It never puts anybody on a list. Showing up in your analytics isn't permission to email anybody.
- It never shows your key back. It's locked away the moment it arrives.
- It never stores an event you didn't name.
It's under Connections → PostHog, and only an owner or an admin can connect or disconnect it.
Setting it up
Connections → PostHog → Connect walks you through five steps.
1. Name your project. Pick where your PostHog is (US cloud, EU cloud, or your own address) and
give the project id: the number after /project/ in PostHog's own address.
2. Paste a personal API key. In PostHog, open Settings → Personal API keys and create one, scoped to this project, with read access to:
| Scope | What it's for |
|---|---|
query:read |
the queries that read the summary and the named events |
person:read |
the email on a person, which is how somebody is matched here |
event_definition:read |
the list of event names you tick in step 3 |
It starts with phx_. The phc_ key is your project's public key, which can't read anything;
Kicklace refuses it by name.
3. Choose the events that count. Kicklace shows the event names your project has seen, newest
first. Tick up to twelve. A name is folded on the way in, so Project Created becomes
project_created. Where the folded name is one Kicklace already knows (signup, activated,
purchase, churned), it is that event and moves people the way it always does. Anything else
is a name of your own and moves nobody.
4. Read the history. The hourly read starts thirty days back. Read the history reads all of it: everybody PostHog has seen with an address, with the day they were first seen, and every one of your named events on its own day. Nothing is sent and nobody is put on a list, and pressing it again carries on from where it stopped.
5. Hear them the moment they happen (optional). A webhook destination in PostHog posts your named events the second they happen, so what follows an activation can go while somebody is still in your product. The fifth step gives you three things to paste into PostHog under Data pipeline → Destinations → Webhook: the address, one header, and the body. The header is a secret Kicklace shows once, because PostHog's webhook destination signs nothing.
The body asks for exactly what Kicklace reads:
{
"uuid": "{event.uuid}",
"event": "{event.event}",
"timestamp": "{event.timestamp}",
"distinct_id": "{event.distinct_id}",
"email": "{person.properties.email}",
"properties": {event.properties}
}
Set the destination's own filter to the events you ticked.
What lands
On a person, three fields made once and filled every hour:
| Field | What it is |
|---|---|
| Last seen in the product | the day of their most recent event in PostHog |
| Events, 30 days | how many events they fired in the last 30 days |
| Events, 7 days | and in the last 7 |
They're ordinary fields: sort by them, filter on them, count them.
A person is found by email address. Somebody PostHog knows only by an id is nobody: Kicklace won't make a person out of an id with no address beside it.
On a timeline, one row per named event, with the day it happened and a few of its own properties.
An event lands once, whichever of the three ways it arrives, because each writes it under PostHog's
own uuid. The summary fires nothing and doesn't touch a person's last-activity date, so "quiet for
thirty days" stays true of somebody who really is quiet.
When it goes wrong
Whatever PostHog refuses with is what the screen says, in PostHog's own words, and your key is in none of it. The hourly read tries again next hour; the history waits for you.
Disconnecting stops the reads. Everybody who came in through it stays.
From Claude
read_history with source: "posthog" starts or carries on the history read, and takes no key: the
key goes into the form, never into a message.