Use Cases & Examples

Practical examples of how to use the Hooklistener Datastore.

Use cases

• Feature flags — store toggle state as JSON, read it from your app via API
• Configuration management — centralize app config accessible from any interface
• Caching webhook data — store processed webhook payloads for later retrieval with TTL
• Shared state across integrations — pass data between webhook handlers or MCP workflows
• Temporary tokens — store short-lived credentials with automatic expiration
• Environment-specific config — use namespaces to separate dev, staging, and production settings

Examples

Store and retrieve a feature flag

Create a feature flag:

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": "feature:new-checkout",
      "value": {"enabled": true, "rollout_percent": 25},
      "description": "New checkout flow feature flag"
    }
  }'

Read it from your application:

curl https://app.hooklistener.com/api/v1/datastore/entries/feature:new-checkout \
  -H "Authorization: Bearer hklst_your_api_key"

Response:

{
  "data": {
    "id": "ds_abc123",
    "key": "feature:new-checkout",
    "namespace": "default",
    "value": {"enabled": true, "rollout_percent": 25},
    "description": "New checkout flow feature flag",
    "expires_at": null,
    "created_at": "2026-03-15T10:00:00Z",
    "updated_at": "2026-03-15T10:00:00Z"
  }
}

Cache a Stripe webhook event with TTL

Store webhook data temporarily for downstream processing:

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": "stripe:evt_1abc123",
      "namespace": "webhook-cache",
      "value": {
        "type": "payment_intent.succeeded",
        "customer": "cus_xyz",
        "amount": 2500,
        "currency": "usd"
      },
      "ttl_seconds": 7200,
      "description": "Cached Stripe payment event"
    }
  }'

This entry will expire after 2 hours.

Multi-environment config with namespaces

Store the same keys in different namespaces for each environment:

# Production config
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": "config:api:rate-limit",
      "namespace": "production",
      "value": {"requests_per_minute": 1000, "burst": 50}
    }
  }'

# Staging config (lower limits)
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": "config:api:rate-limit",
      "namespace": "staging",
      "value": {"requests_per_minute": 100, "burst": 10}
    }
  }'

Retrieve config for a specific environment:

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

MCP workflow: store and retrieve data

Using the Hooklistener MCP server with an AI assistant:

You: "Save the last Stripe webhook customer ID for later"

The assistant calls set_datastore_key with key "stripe:last-customer" and the customer ID as the value.

You: "What was that Stripe customer ID I saved earlier?"

The assistant calls get_datastore_key with key "stripe:last-customer" and returns the stored value.

FAQ

What happens when an entry expires? Expired entries are immediately excluded from all queries. A background worker periodically removes them from the database. You don't need to delete them manually.

Can I store binary data? No. Values must be valid JSON — strings, numbers, booleans, arrays, objects, or null.

What counts toward my entry limit? All non-expired entries across all namespaces count toward your plan's limit. Updating an existing entry does not increase the count.

Can I bulk-import entries? Yes. The upsert endpoint supports bulk operations — send multiple entries in a single request and they are applied atomically. If the operation would exceed your plan limit, the entire batch is rolled back.

How is the Datastore different from Secrets? Secrets are encrypted at rest and designed for sensitive credentials like API keys or tokens. The Datastore is for general-purpose key-value storage — configuration, feature flags, cached data, and shared state. Datastore values are not encrypted.

Is the Datastore suitable for high-throughput use? The Datastore is designed for configuration and state management, not high-frequency reads or writes. For use cases requiring thousands of operations per second, consider a dedicated database.