Event Logs and Exceptions

Key Concepts:

• Events: Complete audit trail of all system activities (successful and failed)

• Exceptions: Focused view of issues requiring human attention

• Timeline: Change history tracking for both events and exceptions

Event Logs Data Model

The Events system in Pipe17 provides a comprehensive audit trail of all activities and data flows within the app. Events track requests and responses for operations like creating orders, updating inventory, sending shipping requests, and more. They serve as a critical tool for monitoring, troubleshooting, and understanding the flow of data both into and out of Pipe17.

Event Logs Key Fields

Identification Fields

• eventId: Unique identifier for the event (system-generated)

• requestId: API request ID that generated this event

• entityId: ID of the entity this event relates to (e.g., order ID, product ID)

• entityType: Type of entity this event relates to (e.g., "orders", "products", "inventory", "shipments", "fulfillments")

• extEntityId: External entity ID (from the connected system)

Event Classification

• source: Event type source

  • api: Direct API call

  • api-webhook: Webhook received from external system

  • custom: Custom user-created event

• direction: Route/mapping direction

  • in: Information flowing into Pipe17 (e.g., a new order from a sales channel)

  • out: Information flowing out of Pipe17 (e.g., a shipping request sent to a 3PL)

• operation: Name of operation with entity

  • Common operations: create, update, delete, poll, fetch, list

  • Specialized operations: acknowledge, sync, replay, cancel, void, commit, ingest, adjust

• keywords: Array of searchable keywords associated with the event

• integration: Integration ID that created or processed the event

• isBatch: Indicates if the event is for a batch action

Event Batching Details

For batch operations, additional tracking fields:

• batchId: Batch identifier for grouped events

• batchSize: Total number of events in the batch

• batchIndex: Position of this event within the batch (0-based)

Request Information

• request: Object containing details about the API request

  • method: HTTP method (GET, POST, PUT, DELETE)

  • url: Request URL

  • headers: Request headers

  • body: Request body content

  • authobj: Request authorization information

Response Information

• response: Object containing details about the API response

  • status: HTTP status code

  • message: Response message

  • headers: Response headers

  • body: Response body content

  • retries: Number of retry attempts

Status and Timing

• status: Event status

  • pending: Event has been created but not yet processed

  • processing: Event currently being processed

  • acknowledged: Event has been sent by Pipe17, but no success confirmation received

  • completed: Event has been successfully processed

  • failed: Event processing failed

  • retrying: Event is being retried after failure

• timestamp: When the event was triggered

• duration: Operation duration in milliseconds

Performance Metrics

Detailed timing breakdown for performance analysis:

• queueTime: Time spent in queue before processing (milliseconds)

• processingTime: Actual processing time (milliseconds)

• networkTime: Network request/response time for external calls (milliseconds)

Event Replay and Retry

Fields for tracking event replay functionality:

• replayable: Boolean flag indicating if this event can be replayed

• replayedAt: Timestamp when this event was replayed

• originalEventId: Reference to original event if this is a replayed event

• replayCount: Number of times this event has been replayed

• maxRetries: Maximum number of retry attempts allowed

• retryAfter: Timestamp for next retry attempt

Webhook-Specific Fields

For events with source: api-webhook:

• webhookId: Webhook subscription ID

• webhookTopic: Webhook topic (e.g., "orders", "shipments", "products", "inventory", "fulfillments")

• webhookUrl: Webhook destination URL

• webhookSignature: Webhook signature for validation

• webhookVerified: Boolean indicating if webhook signature was verified

Exception References

• exceptionId: Reference to exception created by this event (if any)

• exceptionCategories: Array of exception category references

Data Payload

• payload: Snapshot of entity data at time of event

  • Compressed for large payloads

  • Contains full entity state or delta changes

• diff: Changes made to entity (for update operations)

  • fieldName: Field that changed

  • oldValue: Previous value

  • newValue: New value

System Fields

• createdAt: When the event was created in Pipe17 (system-generated)

• updatedAt: When the event was last updated in Pipe17 (system-generated)

• userId: API user ID that initiated the event

• orgKey: Organization this event belongs to (multi-tenant isolation)

Event Status Lifecycle

1. Creation: When an operation is performed (e.g., creating an order), an event is created with initial status pending.

2. Processing:

   • For in direction events (data coming into Pipe17), the system processes the request and updates the status to processing, then completed if successful or failed if there's an error.

   • For out direction events (data going out to external systems), the status is set to acknowledged when the request is sent to the external system.

3. Completion/Failure:

   • acknowledged events typically transition to completed when confirmation is received from the external system.

   • If an error occurs during processing, the status becomes failed.

   • Failed events may automatically enter retrying status if retry logic is enabled.

4. Replay: Failed events can be replayed (rerun) once the underlying issue is resolved. When replayed:

   • A new event is created with reference to the original via originalEventId

   • The replayCount is incremented on the original event

   • The replayedAt timestamp is recorded

Status Flow Diagram:

pending → processing → completed
   ↓          ↓
   ↓       failed → retrying → completed
   ↓          ↓         ↓
   ↓          ↓      failed (max retries)
   ↓          ↓
acknowledged → completed

Event Retention Policy

Retention Periods:

• Standard Events: Retained for 90 days

• Failed Events: Retained for 180 days (extended retention for troubleshooting)

• Critical Events: Retained for 1 year (configurable per organization)

Archival:

• Events older than retention period are archived to cold storage

• Archived events can be retrieved for compliance and audit purposes

• Export events before archival for long-term offline storage

Compression:

• Large event payloads are automatically compressed

• Compression reduces storage costs and improves query performance

Best Practice: Do not rely on events for long-term data storage. Export critical events for compliance and archival purposes.

Exceptions Data Model

Exceptions in Pipe17 represent error conditions and issues that need attention across entities. They are created when the system encounters problems that it cannot automatically resolve based on the current configuration. Exceptions provide visibility into issues that require human intervention.

Exceptions Key Fields

Identification Fields

• exceptionId: Unique identifier for the exception (system-generated)

• entityId: ID of the entity this exception relates to

• entityType: Type of entity this exception relates to

• extEntityId: External entity ID from the connected system

• relatedEntityId: ID of a related entity (e.g., for shipping request exceptions, this might be the order ID)

• relatedEntityType: Type of the related entity

Exception Classification

• exceptionType: Type of exception (see complete list below)

• categoryId: Exception category ID for grouping related exception types

• exceptionPriority: Priority level

  • critical: Requires immediate attention, blocking operations

  • high: Important issue, needs timely resolution

  • medium: Standard issue, normal resolution timeframe

  • low: Minor issue, can be addressed during routine maintenance

• exceptionSeverity: Severity level (impact assessment)

  • critical: Severe impact, multiple operations affected

  • high: Significant impact on operations

  • medium: Moderate impact

  • low: Minimal impact

• origin: Origin type of the exception

  • external: From external system (integration failure, invalid data from channel)

  • internal: From Pipe17 system (routing failure, validation failure)

  • user: User-initiated action caused exception

  • automated: Automated process triggered exception

  • unknown: Origin not determined

Content and Resolution

• exceptionDetails: Detailed error message or explanation

• recommendation: Suggested resolution steps

• aiTip: AI-generated tip for resolving the exception

• status: Exception status

  • active: Exception is currently active and unresolved

  • dismissed: Exception has been dismissed without resolution

  • resolved: Exception has been resolved

Resolution Tracking

Fields tracking who resolved the exception and when:

• resolvedAt: Timestamp when exception was resolved

• resolvedBy: User ID who resolved the exception

• resolvedByType: Type of resolver

  • user: Manually resolved by user

  • integration: Resolved by integration

  • automated: Automatically resolved by system

• resolutionNote: User-provided notes about resolution

• resolutionMethod: How the exception was resolved

  • manual: Manual intervention

  • replay: Event replayed after fix

  • config: Configuration change

  • automated: Auto-resolved by system

• dismissedAt: Timestamp when exception was dismissed

• dismissedBy: User ID who dismissed the exception

• dismissedReason: Reason for dismissal

  • false_positive: Not an actual error

  • duplicate: Duplicate of another exception

  • resolved_elsewhere: Fixed through other means

  • no_action_needed: No action required

  • other: Other reason (see dismissalNote)

• dismissalNote: User-provided notes about dismissal

Assignment and Ownership

Exception assignment for team collaboration:

• assignedTo: User ID assigned to resolve this exception

• assignedAt: Timestamp when exception was assigned

• assignedBy: User ID who made the assignment

• assignmentNote: Notes about the assignment

Notification Tracking

Track notifications sent for this exception:

• notified: Boolean flag indicating if notifications were sent

• notifiedAt: Timestamp when notifications were sent

• notificationChannels: Array of notification channels used

  • email: Email notification

  • slack: Slack notification

  • webhook: Webhook notification

  • sms: SMS notification

  • inapp: In-app notification

Occurrence Tracking

Track exception patterns and recurrence:

• occurrences: Total number of times this exception has occurred

• firstOccurredAt: Timestamp of first occurrence

• lastOccurredAt: Timestamp of most recent occurrence

• suppressUntil: Timestamp to suppress duplicate exceptions until (deduplication)

• similarExceptions: Array of similar exception IDs (for pattern detection)

Event References

• eventId: Reference to event that caused this exception (primary trigger)

• eventIds: Array of related event IDs (all events related to this exception)

Metadata

• integration: Reference to integration that created the exception

• tags: Tags assigned to the exception for categorization

• customFields: Array of custom key-value pairs for organization-specific data

• internal: Object for internal information

• sourceDoc: Vendor source document reference

Timeline

• timeline: Array of timeline entries tracking updates to the exception (see Timeline Data Model)

System Fields

• createdAt: When the exception was created (system-generated)

• updatedAt: When the exception was last updated (system-generated)

• orgKey: Organization this exception belongs to (multi-tenant isolation)

• autoEngUpdateStatus: Status indicating whether the automation engine may update the entity

• autoEngUpdateStatusUpdatedAt: When the autoEngUpdateStatus was last updated

Complete Exception Types

Integration and Sync Exceptions:

• eGeneric: General exception

• eSyncFailure: Synchronization failure

• eIntegrationDown: Integration service unavailable

• eAuthFailure: Authentication failure with external system

• eRateLimitExceeded: API rate limit exceeded

• eTimeout: Operation timeout

• eConnectionFailure: Connection to external system failed

• eWebhookValidation: Webhook signature validation failed

Data Validation Exceptions:

• eInvalidData: Invalid data format

• eInvalidAddress: Invalid shipping address

• eInvalidSKU: Invalid product SKU

• eInvalidEmail: Invalid email address

• eInvalidPhone: Invalid phone number

• eMissingRequired: Missing required fields

• eValidationFailure: General data validation failed

• eDuplicateEntity: Duplicate entity detected

• eMappingFailure: Field mapping failure between systems

Inventory Exceptions:

• eOutOfStock: Product out of stock

• eLow: Low inventory threshold reached

• eInventoryMismatch: Inventory discrepancy between systems

• eNegativeInventory: Inventory went negative (oversold)

Routing Exceptions:

• eRouteNotFound: No routing rule found for order

• eRouteOutOfStock: Routing failed due to insufficient inventory at all locations

• eRouteLocationDown: Routing failed because preferred location unavailable

• eRouteNoCapacity: Routing failed due to capacity constraints

Order and Fulfillment Exceptions:

• eOrderValidation: Order validation failed

• eOrderCancel: Order cancellation issue

• eFulfillmentFailure: Fulfillment processing failed

• eShipmentFailure: Shipment processing failed

• eTrackingInvalid: Invalid tracking number

• eAddressValidation: Address validation service failed

Product Exceptions:

• eProductNotFound: Product not found in system

• eProductSyncFailure: Product sync to channel failed

• eVariantMismatch: Product variant mismatch

• eBundleValidation: Bundle configuration invalid

System Exceptions:

• eSystemError: Internal system error

• eQueueOverflow: Message queue overflow

• eDatabaseError: Database operation failed

• eConfigurationError: System configuration error

Exception Status Lifecycle

1. Creation: When an error condition is detected, an exception is created with status active.

2. Assignment (Optional): Exception may be assigned to a team member for resolution.

3. Resolution:

   • If the underlying issue is fixed, the exception status can be updated to resolved.

   • Resolution is tracked with resolvedAt, resolvedBy, and resolutionNote.

   • If the exception is no longer relevant or is a false positive, it can be dismissed.

   • Dismissal is tracked with dismissedAt, dismissedBy, and dismissedReason.

4. Automation: Some exceptions may be automatically resolved by the system when the underlying condition is corrected (e.g., inventory replenished, integration restored).

Status Flow:

active → assigned → resolved
   ↓        ↓
dismissed ← dismissed

Timeline Data Model

Both Events and Exceptions include a timeline component that tracks changes to their status and other attributes over time. The timeline provides a complete audit trail of all modifications.

Timeline Key Fields

Core Fields

• timestamp: When the timeline entry was created

• operation: Type of operation

  • create: Entity created

  • update: Entity updated

  • status_change: Status changed

  • assign: Exception assigned

  • resolve: Exception resolved

  • dismiss: Exception dismissed

  • replay: Event replayed

  • notify: Notification sent

• status: Entity status after the change

• integrationId: Integration that created/updated the entity

• userId: Author ID (user who made the change)

• apikeyId: ID of the change request API key

• eventId: Event ID in the API Event Log

• logId: Log entry ID

Field Change Tracking

Detailed tracking of what changed:

• fieldChanges: Array of field-level changes

  • fieldName: Name of the field that changed

  • oldValue: Previous value (before change)

  • newValue: New value (after change)

  • changeType: Type of change

    • create: Field added

    • update: Field value changed

    • delete: Field removed

Example:

{
  "fieldChanges": [
    {
      "fieldName": "status",
      "oldValue": "active",
      "newValue": "resolved",
      "changeType": "update"
    },
    {
      "fieldName": "resolvedBy",
      "oldValue": null,
      "newValue": "user-123",
      "changeType": "create"
    }
  ]
}

Change Context

Additional context about the change:

• note: User-provided note about the change

• reason: Reason for the change

• source: Source of the change

  • ui: Changed via user interface

  • api: Changed via API call

  • integration: Changed by integration

  • automation: Changed by automated process

  • webhook: Changed via webhook

• ipAddress: IP address of the requester

• userAgent: User agent string (browser/client information)

Timeline Entry Types

Timeline entries can represent various types of events:

1. Status Changes: Entity status transitions (e.g., pending → completed, active → resolved)

2. Field Updates: Changes to specific fields with old/new values

3. Assignments: Exception assigned to user

4. Resolutions: Exception marked as resolved

5. Dismissals: Exception dismissed

6. Notifications: Notification sent

7. Replays: Event replayed

8. Comments: User comments added

Example Timeline Entry (Exception Resolution):

{
 "timestamp": "2025-11-04T15:30:00Z",
 "operation": "resolve",
 "status": "resolved",
 "userId": "user-123",
 "fieldChanges": [
   {
     "fieldName": "status",
     "oldValue": "active",
     "newValue": "resolved",
     "changeType": "update"
   },
   {
     "fieldName": "resolvedBy",
     "oldValue": null,
     "newValue": "user-123",
     "changeType": "create"
   }
 ],
 "note": "Fixed routing configuration and replayed failed events",
 "reason": "Configuration issue resolved",
 "source": "ui",
 "eventId": "evt-456"
}

Relationship Between Events and Exceptions

Events and Exceptions are closely related but serve different purposes:

Causality

Events often lead to the creation of Exceptions when errors occur. For example:

• A failed order creation event (status: failed) → generates an exception (e.g., eInvalidAddress)

• A failed inventory sync event → generates eSyncFailure exception

• A failed shipment request event → generates eFulfillmentFailure exception

Reference

• Exceptions reference Events: Exceptions reference the Events that caused them through:

  • eventId: Primary triggering event

  • eventIds: Array of all related events

  • Timeline entries include eventId field

• Events reference Exceptions: Events can reference exceptions they created:

  • exceptionId: Exception created by this event

  • exceptionCategories: Categories of exceptions related to event

Event-Entity Relationships

Events link to entities via:

• entityId + entityType: Direct entity reference

• Examples:

  • Event → Order (entityType: "orders", entityId: "order-123")

  • Event → Product (entityType: "products", entityId: "prod-456")

  • Event → Shipment (entityType: "shipments", entityId: "ship-789")

Exception-Entity Relationships

Exceptions can relate to multiple entities:

• Primary Entity: entityId + entityType

• Related Entity: relatedEntityId + relatedEntityType

• Example: Routing exception relates to both order (entityId) and shipment (relatedEntityId)

Resolution

Resolving an Exception often involves:

1. Identifying the failed Event(s) that caused it

2. Fixing the underlying configuration or data issue

3. Replaying (rerunning) the failed Event

4. Marking the Exception as resolved

Event Chaining

Events can chain together to show data flow:

1. Order Create Event (in) → Order created in Pipe17

2. Order Routing Event (internal) → Routing engine processes order

3. Shipment Create Event (internal) → Shipment request created

4. Shipment Send Event (out) → Shipment sent to 3PL

Chain is tracked via entityId references and timeline entries.

Visibility

• Events: Provide a comprehensive audit trail of all activities (successful and failed)

• Exceptions: Highlight specific issues that need human attention

• Timeline: Shows change history for both events and exceptions

API Operations Reference

Event Logs REST API

Common Query Parameters:

• Identification: eventId, requestId, entityId, entityType, extEntityId

• Classification: source, direction, operation, integration, isBatch

• Status: status (pending, processing, acknowledged, completed, failed, retrying)

• User: userId, orgKey

• Date Range: since, until (createdAt), timestampSince, timestampUntil

• Search: keywords (full-text search in keywords array)

• Pagination: skip (default: 0), count (default: 100, max: 1000)

• Sorting: order (field to sort by, e.g., "createdAt", "timestamp")

• Fields: keys (comma-separated list of fields to return)

Exceptions REST API

Common Query Parameters:

• Identification: exceptionId, entityId, entityType, extEntityId

• Related: relatedEntityId, relatedEntityType

• Classification: exceptionType, categoryId, priority, severity, origin

• Status: status (active, dismissed, resolved)

• Assignment: assignedTo, unassigned (true/false)

• Integration: integration, orgKey

• Date Range: since, until (createdAt), resolvedSince, resolvedUntil

• Pagination: skip (default: 0), count (default: 100, max: 1000)

• Sorting: order (field to sort by)

• Fields: keys (fields to return)

Practical Applications

Monitoring and Troubleshooting

Event Logs: Used to track the flow of data and identify where and when issues occurred.

• Monitor all API operations across integrations

• Track data flow from external systems into Pipe17

• Track data flow from Pipe17 to external systems

• Identify slow operations via duration, queueTime, processingTime

Exceptions: Provide focused visibility into specific problems that need attention.

• Dashboard of active issues requiring resolution

• Prioritized view based on priority and severity

• Assignment to team members for resolution

• Tracking of resolution progress

Event Search Examples

Find all failed order creation events in last 24 hours:

Find all events for a specific order:

Find all webhook events from Shopify integration:

Find all events with specific keyword:

Find slow operations (duration > 5 seconds):

Common Event and Exception Scenarios

Order Processing

1. Order Creation Event

• Direction: in

• Operation: create

• EntityType: orders

• Example: New order received from Shopify

{
  "eventId": "evt-001",
  "direction": "in",
  "operation": "create",
  "entityType": "orders",
  "source": "api-webhook",
  "webhookTopic": "orders",
  "integration": "shopify-123",
  "status": "completed"
}

2. Order Routing Event

• Direction: Internal (no direction field)

• Operation: route

• EntityType: orders

• Example: Order Routing Engine determines fulfillment location

3. Routing Exceptions If routing fails, exceptions are created:

• eRouteNotFound: No routing rule matches this order

  • Resolution: Create routing rule for product/location combination

• eRouteOutOfStock: All potential locations are out of stock

  • Resolution: Restock inventory or adjust routing rules

Inventory Management

1. Inventory Update Events

• Direction: in

• Operation: update, ingest, adjust

• EntityType: inventory

• Example: Inventory sync from WMS

2. Low Inventory Exceptions

• eLow: Inventory level fell below threshold

  • Priority: medium or high (depending on product)

  • Resolution: Restock inventory, adjust thresholds, or mark as expected

Integration Issues

1. Connection Failure Events

• Status: failed

• Example: API call to external system times out

{
  "eventId": "evt-002",
  "status": "failed",
  "response": {
    "status": 504,
    "message": "Gateway Timeout"
  }

2. Sync Failure Exceptions

• eSyncFailure: Data synchronization with external system failed

  • Recommendation: Check integration credentials, verify API status

  • Resolution: Fix integration configuration, replay failed events

3. Integration Outage

• eIntegrationDown: Multiple consecutive failures indicate integration is down

  • Priority: high or critical

  • Notification: Immediate alert to operations team

  • Resolution: Wait for integration to recover, retry automatically

Fulfillment Scenarios

1. Shipment Creation Event

• Direction: out

• Operation: create

• EntityType: shipments

• Example: Shipment request sent to 3PL

2. Fulfillment Failure Exception

• eFulfillmentFailure: Warehouse could not process shipment

  • Recommendation: Check inventory availability, verify address

  • Resolution: Fix issue and reroute to alternate location if needed

3. Invalid Tracking Exception

• eTrackingInvalid: Tracking number format invalid

  • Recommendation: Verify tracking number format, contact carrier

  • Resolution: Update tracking number, notify customer

Product Sync Scenarios

1. Product Update Event

• Direction: out

• Operation: update

• EntityType: products

• Example: Product update sent to marketplace

2. Product Sync Failure Exception

• eProductSyncFailure: Product failed to sync to sales channel

  • Recommendation: Check channel connection, verify product data

  • Resolution: Fix data issues, replay sync event

Webhook Processing

1. Webhook Received Event

• Source: api-webhook

• webhookTopic: Topic of webhook (orders, products, etc.)

• webhookVerified: Signature verification result

2. Webhook Validation Exception

• eWebhookValidation: Webhook signature invalid or expired

  • Recommendation: Verify webhook secret configuration

  • Resolution: Update webhook configuration in integration settings

Quick Reference Tables

Event Status Values

Event Direction Values

Event Source Values

Common Event Operations

Exception Status Values

Exception Priority Values

Exception Severity Values

Exception Origin Values

Common Exception Types by Category

Integration & Sync

Data Validation

Inventory

Routing

Fulfillment

Need Help?

If you need additional assistance:

• Use Ask Pippen, our AI agent, located at the top of the app page.

• Submit a support request with as much relevant detail as possible. Learn how to submit a request.

• For urgent issues, email us directly at support@pipe17.com.

We're here to help you succeed with your operations.