Skip to main content
Use this page when an event was submitted but expected downstream behavior did not happen.

​
Understand The Two Event Views

  1. Events: canonical processed history.
  2. Incoming Events: processing pipeline state.
If an event does not appear in Events yet, always check Incoming Events first.

​
Incoming Status Meanings

States:
  • received
  • processing
  • processed
  • failed
Suggested labels:
  • received: queued
  • processing: in progress
  • processed: completed
  • failed: action required
Failure qualifiers:
  • failed + retryable=true: worker may retry
  • failed + retryable=false: terminal failure, fix payload and resend

​
Troubleshooting Flow

  1. Check Incoming Events by idempotency key.
  2. Inspect status and process_error.
  3. If processed, open linked canonical event_id.
  4. If failed and retryable=false, correct payload and resend.

​
High-Signal Fields To Inspect

  • idempotency_key
  • status
  • process_error
  • retryable
  • retry_count
  • event_id
  • payload.type
  • payload.email or payload.uid

​
Common Failure Causes

  • no contact identifier provided
  • invalid type value
  • malformed payload shape
  • mismatched event vocabulary across services
  • duplicate semantics with unstable idempotency keys

​
Support Handoff Template

When escalating internally, include:
  1. client_id
  2. idempotency_key
  3. incoming event id
  4. status and process_error
  5. payload excerpt (without sensitive fields)
  6. approximate submission timestamp

​
Recovery Playbook

  1. Correct producer payload or mapping logic.
  2. Regenerate deterministic idempotency key only if this is a new logical event.
  3. Resend event.
  4. Verify Incoming Events processed state.
  5. Confirm canonical event appears and tags or workflows react as expected.