Heap and CodeWords: acting on autocaptured behaviour
What autocapture changes about analytics automation, turning retroactive analysis into worklists, enriching user properties from other systems, and alerting without crying wolf.
Osman Ramadan11 min read
On this page
Heap's distinguishing idea is autocapture: it records interactions without you deciding in advance which ones matter, so you can define an event retroactively and get its history rather than starting the clock today. That is genuinely useful and it changes what automation around it should do.
With most analytics tools, the constraint is that you did not instrument the thing you now want to measure. With Heap, the data is usually there and the constraint is the same one every analytics product has: the person who could act on what it knows does not work in the analytics tool.
What we'll cover
- What autocapture changes
- What the Heap API reaches
- Connecting it to CodeWords
- Eight automations worth building
- Turning analysis into worklists
- Building it so it survives
- Limits worth knowing about
- What to build first
- Frequently asked questions
What autocapture changes
Retroactive definition. A question asked today can be answered with months of history, which means an automation built this week can report on behaviour that predates it. That is unusual and worth exploiting.
Less instrumentation work, more definition work. The effort moves from adding tracking code to agreeing what a defined event actually means. Two people defining "activated" differently produces two different numbers from the same data.
Properties still have to be sent. Autocapture records interactions; it does not know your customer's plan, their account value, or whether they are in a trial. Those are user and account properties you must provide, and they are what makes any of the analysis segmentable.
Noise is the cost. Capturing everything means a great deal of what is captured means nothing, which puts more weight on defined events being maintained rather than accumulating.
The practical consequence for automation: enriching properties matters more here than instrumenting events, which is the reverse of most analytics integrations.
What the Heap API reaches
Server-side track lets you send events from a backend, for the things that never touch a browser: payments, provisioning, batch outcomes.
User and account properties can be set through the identify and account APIs, which is where enrichment from your own systems belongs.
Data export and connectors deliver event data to a warehouse, which is the right route for anything genuinely analytical rather than querying repeatedly through an API.
Defined events and segments are configured in Heap and are what your reporting should reference, so that the definitions stay where your team can see them.
Webhooks and integrations push segment membership changes outward to other tools.
The shape that works: define events and segments in Heap where they are visible, enrich properties from outside so those definitions can be segmented meaningfully, and export to a warehouse when you need to join against anything else.
Connecting it to CodeWords
CodeWords connects to more than 3,000 integrations, and the connection is made once and reused.
- Open CodeWords and start a new automation.
- Describe what should happen in plain language to Cody, the automation builder: which behaviour matters, who should hear about it, and where.
- Authorize the connection with your Heap app ID and API credentials, scoped to the environment involved.
- Describe the exceptions: a user with no matching account record, an empty segment, a property that is missing rather than false.
- Run it against a past period where you already know what it should find.
You describe the outcome; Cody builds it, connects it, and deploys it. The free plan covers light use, with Pro at $39 per month and Business at $100 per month as usage grows; details are on the pricing page.
Eight automations worth building
Property enrichment. Push plan, account value, contract date, industry, and support status from your systems onto Heap's user and account properties. Everything analytical becomes more useful once this exists, and without it segmentation is limited to behaviour alone.
Server-side events for what browsers never see. Payments, provisioning, cancellations, and batch job outcomes. Autocapture cannot see these and the funnel is incomplete without them.
Activation worklists. Accounts that signed up and have not reached the defined activation event, delivered as a named list to whoever owns onboarding rather than as a percentage.
Silent disengagement. Accounts whose activity has fallen against their own recent baseline, raised before a renewal conversation rather than during it.
Feature adoption reporting after release. Who used it, from which segments, and who tried once and did not return. The last group is the interesting one.
Funnel drop alerting with the segment named. Not "conversion fell" but which step, for which segment, by how much against its own normal range.
Deployment and campaign annotation. Record releases and campaign launches alongside the behavioural data, so a movement has a candidate explanation rather than an investigation.
Reverse sync to operational tools. Push segment membership into the CRM or the support tool, so the people who act on it see it where they work.
Turning analysis into worklists
The single most useful idea on this page, and it applies to every analytics product.
A percentage is not actionable. "Activation is down three points" tells a team something is wrong and gives them nowhere to start.
A list is actionable. "These fourteen accounts signed up in the last ten days and have not created their first project" is somebody's Tuesday morning.
Deliver it where the work happens. The CRM for account managers, the support queue for support, a channel for the product team. Not a dashboard.
Include enough to act. The account name, who owns it, when they signed up, what they did do, and a link straight to the record. Anything missing becomes a lookup, and lookups are where worklists go to be abandoned.
Keep it short. A list of fourteen gets worked. A list of four hundred gets ignored, and a list that is always four hundred means the threshold is wrong rather than the team.
Close the loop. Send an event back when somebody acts, so you can later compare accounts that were contacted against comparable ones that were not. Without that you have activity and no evidence.
Building it so it survives
Keep identity consistent. Heap's identity, your CRM's account ID, and your database's user ID are three different things. Decide the mapping explicitly and send it as a property at signup, because retrofitting it across history is genuinely painful.
Sanity check before sending. An empty segment may mean nothing is wrong or may mean a definition changed. Those look identical to an automation that only checks for problems.
Report success as well as exceptions. A brief confirmation that the checks ran makes silence meaningful.
Do not recreate Heap's definitions in your automation. Reference the defined events and segments so the logic stays visible to the team that maintains them.
Log what was sent. When a figure is disputed, the record of exactly which properties and events the automation wrote is the difference between an answer and a guess.
Limits worth knowing about
Rate limits apply to the server-side APIs, so bulk property updates need batching and pacing.
Property updates are not instantaneous in their effect on segments, so an automation that writes a property and immediately reads a segment may not see the change.
Autocapture depends on stable markup. A redesign can change what an event definition matches, which is the analytics equivalent of a broken selector, and it fails silently as a metric that quietly drops.
Data retention varies by plan, which matters for the retroactive analysis that is the main reason to use Heap at all.
Volume affects cost on session or event-based plans, so an automation sending many server-side events has a pricing implication worth understanding first.
What to build first
Property enrichment: push plan, value, and account details from your own systems into Heap. It is invisible, it makes every existing report and segment more capable immediately, and you can verify it by opening one user and looking.
Two habits make the difference. Run it against a sample first and check the properties landed on the right people, since an identity mapping problem is much cheaper to find on ten records than on ten thousand. And have it report what it wrote, because a silent enrichment job is indistinguishable from a broken one.
Frequently asked questions
Does autocapture mean I do not need to send anything?
It means you do not need to instrument interface interactions in advance. You still need to send user and account properties, and server-side events for anything that never touches a browser, such as payments or provisioning. Those are the parts automation should own.
Why not just query Heap when I need an answer?
For exploration, do. For anything recurring, the problem is that somebody has to remember to look. An automation that delivers the answer where people work converts a question nobody asks into a list somebody works through.
How do I connect Heap identities to our CRM?
Send a stable account identifier as a property at signup and use that as the join key. Email is tempting and unreliable, since people change addresses and share them, and correcting the mapping retroactively across historical data is the kind of project nobody budgets for.
What happens when the site is redesigned?
Autocapture keeps capturing, and defined events matching on markup may stop matching. This shows up as a metric quietly dropping rather than an error, so it is worth checking defined events after any significant interface change, and worth alerting on events that stop firing entirely.
Can I send events from the backend?
Yes, through the server-side track API, and you should for anything a browser never sees. A funnel missing its payment step because payment happens server-side is a funnel that will mislead everyone who reads it.
How do I avoid alert fatigue?
Compare against the same hour of the same weekday rather than a flat threshold, require the deviation to persist across intervals, name the affected segment in the alert, and delete any alert nobody has acted on in a month. The measure is actions taken, not alerts sent.
Should the automation define new events?
Define them in Heap, where the team can see and maintain them, and have the automation reference them. Recreating the definition inside an automation means the same logic exists in two places and drifts, and the drift is invisible until two numbers disagree.
What should I do when a defined event stops firing?
Treat it as an incident rather than a curiosity, because it usually means a redesign changed what it matched. Alerting on events that go to zero is as important as alerting on metrics that move, and it is the one most analytics setups are missing.
Can I join Heap data with our own database?
Through an export or warehouse connector rather than by repeatedly querying the API. Once both are in the same warehouse the joins are ordinary SQL, and that is a far better foundation for anything analytical than an automation stitching two APIs together.
How do I keep defined events from accumulating?
Review them quarterly and delete the ones nothing references. Autocapture makes defining events cheap, which means they proliferate, and a workspace with two hundred definitions nobody can explain is one where two people will pick different ones and produce different numbers.
Should the automation send an event when it acts?
Yes, always. It costs nothing and it is the only way to later compare accounts that were acted on against comparable ones that were not. Without it you have a process generating activity and no evidence it changed anything, which is a comfortable place to stay indefinitely.
What is the most common mistake with autocapture?
Assuming the data is complete because capture is automatic. Anything that happens server-side — payments, provisioning, cancellations — is invisible to it, and a funnel missing those steps will mislead everyone who reads it while looking perfectly plausible.