Labels

Labels are key-value pairs attached to events that enable routing to specific subscriptions. They provide a flexible mechanism for multi-tenancy, environment separation, and custom filtering logic.

Key Points

• Every event must include at least one label
• Subscriptions filter events by matching label values
• Labels enable multi-tenant architectures
• Label matching is case-sensitive and requires exact matches

Minimum Requirement

Every event must include at least one label. The API rejects events with empty labels.

How Labels Work

Event with labels
     |
     v
+------------------------+
| tenant_id: "acme"      |
| environment: "prod"    |
+------------------------+
     |
     v
Hook0 finds subscriptions
with matching labels
     |
     +--------+--------+
     |                 |
     v                 v
+-----------+   +-----------+
| Sub A     |   | Sub B     |
| tenant_id:|   | tenant_id:|
| "acme"    |   | "beta"    |
+-----------+   +-----------+
     |                 |
     v                 x (no match)
  Delivered

Matching Rules

• A subscription receives an event only if all its label filters match the event's labels
• If an event lacks a label that the subscription filters on, the event is not delivered
• Subscriptions can have fewer labels than events (partial matching)
• Label values are case-sensitive and must match exactly

Common Patterns

Pattern	Example Label	Purpose
Multi-tenancy	tenant_id: "acme_corp"	Isolate events per customer
Environment	environment: "production"	Separate prod/staging/dev
Priority	priority: "critical"	Route urgent events differently
Geographic	region: "eu-west-1"	Route by location
Source	source: "mobile_app"	Identify event origin

Naming Best Practices

• Use snake_case for keys: tenant_id, event_source
• Be descriptive: payment_provider not pp
• Avoid sensitive data: never use password, ssn, credit_card
• Use consistent naming across all events

What's Next?

• Events - Attach labels to events
• Subscriptions - Filter events with labels
• Event Types - Categorize your events
• Applications - Manage labels per application