Enrichments

An enrichment is a small, named Python function that runs against an event before it's stored — look something up, compute a flag, reshape a field — without changing whatever system actually sends the event. An event opts in by naming the enrichment in its own enrichment field (see Sending events); anything that doesn't name one is stored exactly as sent.

Creating one

The catalog at Enrichments lists every function you've published, with its version number and when it last changed. Creating one just takes a name — letters, numbers, and underscores, starting with a letter or underscore. That name is permanent once created, since it's the literal value a real event's enrichment field has to match.

The Enrichments catalog — one existing function, and the create form above it.

Writing the function

Every enrichment defines exactly one function:

def enrich(event):    ...    return event

It receives the event as a plain dictionary and must return the dictionary to actually write — return it unchanged for a no-op. A worked example: looking up a customer's phone number in a reference table and attaching what comes back:

def enrich(event):    phone = (event.get("metadata") or {}).get("phone")    if not phone:        return event    row = reference_tables.get("crm_contacts", {}).get(phone)    if not row:        return event    metadata = dict(event.get("metadata") or {})    metadata["is_vip"] = row.get("segment") == "VIP"    metadata["customer_type"] = row.get("customer_type")    metadata["crm_id"] = row.get("crm_id")    metadata["crm_full_name"] = row.get("full_name")    event = dict(event)    event["metadata"] = metadata    return event

reference_tables['<table_name>'].get(<key>) is the standard way to read a reference table from inside an enrichment — it looks a row up by its key column and returns the whole row as a dict, or nothing if the key isn't found. reference_tables.get(name, {}).get(key) is the safer form shown above: it degrades to an empty lookup instead of raising if the table name itself is ever wrong.

Check syntax catches typos and syntax errors on the spot, without running anything — useful while still drafting, before there's a real event worth testing against:

The Python function editor with the CRM-lookup example above, and a passing Check syntax result.

Testing against a real sample

The Test card runs your draft code — including edits you haven't saved yet — against a sample event you provide, and shows exactly what would be written. If the sample's own reference_tables lookups are involved, it fetches the real, current contents of every reference table you can see, so a test result reflects real data, not a guess:

Run test against a sample event with metadata.phone set — the popover shows the real enriched output: is_vip, customer_type, crm_id, and crm_full_name all filled in from the reference table lookup.

In the example above, the sample event only supplied a phone number; everything else in the result — is_vip, customer_type, crm_id, crm_full_name — was filled in by the function reading the crm_contacts reference table. That's the whole point of an enrichment: the sending system only ever needs to know the phone number, and Chomper fills in the rest.

Once a test succeeds, Get curl example turns that same sample into a ready-to-run request against the real ingestion API — a fast way to hand a working example to whoever owns the system that will actually send this kind of event:

Get curl example — a ready POST /api/v1/events request built from the sample event, with a Copy button.

Publishing and changing a function

Clicking Save publishes your edits — every saved change takes effect on the very next event that names this enrichment, and bumps the version number shown next to its name. Republish re-sends the already-saved code without changing anything, which is occasionally worth doing if a function ever needs to be reloaded. History keeps every past version, the same way a dashboard's edit history does, so an earlier version of the code is always one click away.

Note. A function that raises an error, times out, or is named by an event but doesn't exist never blocks the event from being stored — it's written unchanged, with the reason recorded in metadata._enrichment_error. An enrichment can make an event richer, but it can never make an event disappear.