Operate managed integrations

GraphJSON managed integrations connect Segment, Stripe, or Vercel to a workspace collection.

Installation is the beginning of the lifecycle:

approve
  → connect
    → canary
      → validate
        → monitor
          → recover
            → disconnect or retire

Use this guide for the shared operating model, then follow the provider page for source-specific setup.

Inventory the connection#

Record:

GraphJSON workspace:
GraphJSON collection:
Provider account/workspace:
Provider project/source:
Connection owner:
Provider administrator:
Approved event types:
Expected daily volume:
Retention:
Connection date:
Last review:

Avoid configurations known only to the person who clicked Connect.

The provider remains authoritative for whether an event was produced and delivered to its configured destination.

Use a dedicated collection#

Give provider data its own collection when it has a different:

• schema
• sensitivity
• retention period
• owner
• expected volume
• failure response

Examples:

segment_events
stripe_events
vercel_logs

Do not mix raw provider payloads with normalized application events merely because both mention the same account.

You can query across collections with SQL after each source keeps a clear boundary.

Minimize permissions and payloads#

Before authorizing:

1. identify permissions requested by the provider flow
2. confirm the intended provider account
3. restrict eligible projects or sources where supported
4. approve only the event categories needed
5. review whether payloads can contain secrets or personal data
6. name a provider administrator who can revoke access

An integration is not safe merely because it is managed.

For provider payloads:

• avoid raw authorization headers
• avoid complete request/response bodies
• avoid card, credential, or session fields
• minimize free text
• preserve opaque provider object IDs needed for reconciliation

Establish expected behavior#

Write a small contract:

Expected source event:
Expected destination collection:
Expected maximum delay:
Required provider ID:
Required occurrence timestamp:
Expected schema/version:
Expected daily range:
Owner:

This turns “the integration is connected” into something testable.

Run a canary#

Create one safe source event:

Then verify:

1. event appears in the intended collection
2. source event type is correct
3. provider ID is present
4. occurrence time is plausible
5. fields have expected types
6. no secret or excessive payload is present
7. test-mode data cannot pollute production metrics

Do not begin with a real customer incident or payment as the first validation.

Build a health dashboard#

Monitor:

• event volume by source type
• last observed event time
• source occurrence-to-ingestion delay when available
• unknown event types
• missing provider IDs
• schema or field-type drift
• unusually large events
• production/test mode

Example:

SELECT
  toUnixTimestamp(
    toStartOfHour(toDateTime(timestamp, 'UTC'))
  ) AS hour,
  JSONExtractString(json, 'type') AS provider_type,
  count() AS events
FROM provider_events
WHERE toDateTime(timestamp) >= subtractDays(now(), 7)
GROUP BY hour, provider_type
ORDER BY hour, provider_type

Adapt the provider type field after inspecting Samples. Managed integrations can retain provider-specific envelopes.

Alert on absence carefully#

No events can mean:

• connection failure
• healthy low traffic
• provider outage
• a product release changed behavior
• time-zone or filter mistake
• retention removed history

Use:

• expected active hours
• minimum normal volume
• separate producer-health evidence
• an owner who can inspect the provider

Do not alert every minute on a naturally sparse billing event.

Understand retries and duplicates#

Providers can redeliver after timeouts or failures. Preserve the provider event or delivery ID when available.

For exact counts:

WITH unique_events AS (
  SELECT
    JSONExtractString(json, 'id') AS provider_id,
    any(JSONExtractString(json, 'type')) AS provider_type
  FROM provider_events
  WHERE JSONExtractString(json, 'id') != ''
  GROUP BY provider_id
)
SELECT provider_type, count() AS events
FROM unique_events
GROUP BY provider_type

Confirm the correct provider ID path in Samples. Do not deduplicate distinct business events merely because they share an account or timestamp.

Detect payload drift#

Provider schemas evolve.

Monitor:

• unknown event types
• missing expected fields
• string/number changes
• enum additions
• nesting changes
• expanded payload size

Use provider payloads for exploration, then emit normalized application events for metrics whose contract must remain stable.

Do not build a critical metric directly on an undocumented nested provider field without a regression query.

Control volume and retention#

Provider sources can be much wider or higher volume than product events.

Before enabling:

events per day × retention days = approximate stored events

Reduce volume at the source when supported:

• allowlist event types
• exclude noisy projects
• remove verbose logs
• avoid development traffic
• separate test-mode data

Set collection retention from the operational need. Vercel request logs often need a shorter lifecycle than subscription-state changes.

Separate raw and normalized events#

One useful architecture:

provider integration → provider_raw collection
application handler  → normalized_business_events collection

Use raw provider events for:

• investigation
• provider-specific analysis
• reconciliation

Use normalized facts for:

• cross-provider metrics
• stable product dashboards
• customer-facing analytics

Do not double-count one provider fact and its normalized copy in the same metric.

Reconnect safely#

Reconnect when:

• provider authorization was revoked
• administrator ownership changed
• project/source was replaced
• connection configuration is missing

Procedure:

1. record last known destination event
2. confirm current GraphJSON collection and provider scope
3. disconnect stale authorization if appropriate
4. reconnect with the intended provider account
5. send one canary
6. compare provider delivery and GraphJSON Samples
7. watch duplicates around the transition
8. document any gap

Do not repeatedly click Connect while unsure which authorization is active.

Respond to an integration incident#

Events stopped#

1. confirm source still produces events
2. inspect provider destination status
3. confirm authorization and source/project
4. confirm GraphJSON collection and filters
5. compare last success times
6. send a controlled canary
7. reconnect only after recording the gap

Volume spiked#

1. group by provider event type
2. identify project, mode, or source
3. pause the noisy category where safe
4. check retry/redelivery behavior
5. review retention and cost

Payload became unsafe#

1. stop or restrict the source
2. preserve safe identifiers
3. follow the security/privacy incident process
4. do not paste exposed values into support
5. identify affected collection and interval

Duplicates appeared#

1. inspect provider IDs
2. identify redelivery interval
3. determine whether payloads are immutable
4. deduplicate queries
5. reconcile unique provider IDs with the source

Backfills and replay#

A connected integration does not imply unlimited provider history will be backfilled automatically.

Before replay:

• confirm whether the provider supports redelivery
• define the intended historical interval
• preserve provider IDs
• isolate test or replay traffic
• estimate volume
• verify occurrence timestamps
• reconcile after completion

For large history, use the provider export and the migration workflow rather than manually triggering unbounded webhook retries.

Change collection or ownership#

Treat a destination change as a migration:

1. create and configure the new collection
2. record cutover time
3. update provider connection
4. canary
5. verify no gap or overlap
6. update saved queries, dashboards, alerts, and embeds
7. keep the old collection through the review interval
8. retire deliberately

A GraphJSON team change and provider administrator change are separate access reviews.

Disconnect#

Before disconnecting:

1. identify dashboards, queries, alerts, and embeds
2. preserve history required by policy
3. stop normalized downstream producers if related
4. record last provider and GraphJSON events
5. disconnect in the provider and GraphJSON where applicable
6. revoke unused provider authorization
7. verify new events stop
8. choose retention or deletion for the collection

Disconnecting future delivery does not delete existing events.

Quarterly review#

• Provider and GraphJSON owners are current.
• Authorization scope is still necessary.
• Canary procedure still works.
• Volume and retention match expectations.
• Unknown event types are reviewed.
• Provider IDs support deduplication.
• Test and production data remain separate.
• Dashboards still use approved fields.
• Incident and reconnect steps are current.
• Retirement dependencies are inventoried.

Continue with Segment, Stripe, Vercel, or Custom sources.