Namespaces & TTL

Namespaces let you organize datastore entries into logical groups. TTL (time-to-live) lets entries expire automatically.

Namespaces

Every datastore entry belongs to a namespace. If you don't specify one, it defaults to "default".

Entries are uniquely identified by the combination of namespace and key — the same key can exist in multiple namespaces without conflict.

Naming conventions

Namespace names follow the same format as keys: 1–255 characters using letters, digits, _, ., -, :, and /.

Common patterns:

Pattern	Example	Use case
Environment	production, staging, development	Environment-specific configuration
Feature area	billing, notifications, auth	Grouping by domain
Tenant	tenant:acme, tenant:globex	Multi-tenant data isolation

Listing namespaces

Retrieve all namespaces that contain at least one non-expired entry:

curl https://app.hooklistener.com/api/v1/datastore/namespaces \
  -H "Authorization: Bearer hklst_your_api_key"

Filtering by namespace

Pass the namespace query parameter when listing entries:

curl "https://app.hooklistener.com/api/v1/datastore?namespace=production" \
  -H "Authorization: Bearer hklst_your_api_key"

TTL and expiration

Set a TTL when creating or updating an entry to have it expire automatically. Specify the TTL in seconds via ttl_seconds in the API, or in hours via the Dashboard form.

Setting a TTL

curl -X PUT https://app.hooklistener.com/api/v1/datastore/entries \
  -H "Authorization: Bearer hklst_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "entry": {
      "key": "cache:stripe:cus_abc123",
      "value": {"name": "Jane Doe", "plan": "pro"},
      "ttl_seconds": 3600
    }
  }'

This entry will expire 1 hour after creation. The response includes the computed expires_at timestamp.

How expiration works

• Expired entries are excluded from all queries — get, list, and count operations never return them.
• A background worker periodically cleans up expired entries from the database.
• Updating an entry with a new ttl_seconds replaces the previous expiration time.
• To remove a TTL from an existing entry, update it without ttl_seconds.

When to use TTL

• Caching — store processed webhook data for a limited time
• Temporary tokens — auto-expire API tokens or session data
• Rate limiting state — track request counts that reset after a time window
• Feature flags with rollback — enable a feature temporarily, let it auto-disable

Key naming conventions

Keys support letters, digits, and the characters _, ., -, :, /. Use delimiters to create hierarchical, descriptive key names.

Suggested patterns:

config:api:timeout
feature:dark-mode
stripe:customer:cus_abc123
cache:user:42:profile
webhook:github:last-event-id

Using a consistent prefix like config:, cache:, or feature: makes it easy to find related entries with prefix search.