Events & Real-Time Streaming

Insiders

Real-Time

Every Karrio Insiders project comes with comprehensive event management and real-time streaming capabilities, providing event-driven architecture, real-time data synchronization, complete event history, and custom event handlers for complex automation workflows.

Features

Real-Time Event Processing

You don’t have to constantly check for status updates. Our event system instantly publishes notifications when shipping activities occur, enabling immediate responses and real-time user experiences.

Events Management Dashboard

Screenshot: Event streams interface with real-time event monitoring and subscription management

Event Streaming

Continuous event streams for real-time processing with high-throughput, low-latency delivery to multiple subscribers.

Complete Event History

Comprehensive audit trail of all system events with searchable history and detailed event metadata for compliance and debugging.

Custom Event Handlers

Build custom logic to respond to events with flexible event routing and transformation capabilities.

Advanced Event Filtering

Subscribe only to relevant events with powerful filtering by event type, metadata, and custom criteria.

Additional features

Karrio extends events with custom event routing and transformation pipelines.
Every event includes structured metadata and correlation IDs for tracing.
Karrio manages event ordering and guaranteed delivery with replay capabilities.
Support for event aggregation and batch processing for high-volume scenarios.

Data Flow

Event-Driven Architecture

API Reference

GraphQL API

Query Events

1query GetEvents($filter: EventFilter) {
2  events(filter: $filter) {
3    page_info {
4      count
5      has_next_page
6      has_previous_page
7      start_cursor
8      end_cursor
9    }
10    edges {
11      node {
12        id
13        type
14        data
15        test_mode
16        pending_webhooks
17        created_at
18      }
19    }
20  }
21}

Variables:

1{
2  "filter": {
3    "type": ["shipment.created", "tracking.status_updated"],
4    "offset": 0,
5    "first": 20
6  }
7}

Response:

1{
2  "data": {
3    "events": {
4      "page_info": {
5        "count": 1534,
6        "has_next_page": true,
7        "has_previous_page": false,
8        "start_cursor": "MjA5MA==",
9        "end_cursor": "MjA2MA=="
10      },
11      "edges": [
12        {
13          "node": {
14            "id": "evt_af5c3e8b94614bd1b8a0b8e2a5d9e7c4",
15            "type": "shipment.created",
16            "data": {
17              "shipment": {
18                "id": "shp_1234567890",
19                "tracking_number": "1Z999AA1234567890",
20                "carrier_name": "ups",
21                "service": "ups_ground",
22                "status": "purchased",
23                "recipient": {
24                  "person_name": "John Doe",
25                  "city": "Los Angeles",
26                  "state_code": "CA",
27                  "postal_code": "90210",
28                  "country_code": "US"
29                },
30                "shipper": {
31                  "person_name": "Warehouse",
32                  "city": "Chicago",
33                  "state_code": "IL",
34                  "postal_code": "60601",
35                  "country_code": "US"
36                },
37                "parcels": [
38                  {
39                    "weight": 2.5,
40                    "weight_unit": "LB"
41                  }
42                ]
43              }
44            },
45            "test_mode": false,
46            "pending_webhooks": 2,
47            "created_at": "2024-01-15T10:30:00Z"
48          }
49        }
50      ]
51    }
52  }
53}

Get Single Event

1query GetEvent($id: String!) {
2  event(id: $id) {
3    id
4    type
5    data
6    test_mode
7    pending_webhooks
8    created_at
9  }
10}

Variables:

1{
2  "id": "evt_af5c3e8b94614bd1b8a0b8e2a5d9e7c4"
3}

Response:

1{
2  "data": {
3    "event": {
4      "id": "evt_af5c3e8b94614bd1b8a0b8e2a5d9e7c4",
5      "type": "tracking.status_updated",
6      "data": {
7        "tracking": {
8          "id": "trk_1234567890",
9          "tracking_number": "1Z999AA1234567890",
10          "carrier_name": "ups",
11          "status": "in_transit",
12          "events": [
13            {
14              "date": "2024-01-16",
15              "description": "Package has left the origin facility",
16              "location": "Chicago, IL",
17              "code": "DP",
18              "time": "08:30"
19            }
20          ]
21        }
22      },
23      "test_mode": false,
24      "pending_webhooks": 0,
25      "created_at": "2024-01-16T08:30:00Z"
26    }
27  }
28}
29            "person_name": "Acme Corp",
30            "city": "Chicago",
31            "state_code": "IL",
32            "postal_code": "60601",
33            "country_code": "US"
34          }
35        }
36      },
37      "metadata": {
38        "user_id": "usr_1234567890",
39        "organization_id": "org_1234567890",
40        "correlation_id": "corr_1234567890",
41        "source": "api_request"
42      },
43      "version": "2024-01-01"
44    },
45    {
46      "id": "evt_1234567891",
47      "type": "tracking.status_updated",
48      "timestamp": "2024-01-15T14:30:00Z",
49      "data": {
50        "tracking": {
51          "tracking_number": "1Z999AA1234567890",
52          "carrier_name": "ups",
53          "status": "in_transit",
54          "previous_status": "shipped",
55          "estimated_delivery": "2024-01-18T17:00:00Z",
56          "events": [
57            {
58              "code": "DP",
59              "description": "Departed facility",
60              "location": "Los Angeles, CA, US",
61              "timestamp": "2024-01-15T14:30:00Z"
62            }
63          ]
64        }
65      },
66      "metadata": {
67        "organization_id": "org_1234567890",
68        "shipment_id": "shp_1234567890",
69        "correlation_id": "corr_1234567890",
70        "source": "tracking_update"
71      }
72    }
73  ]
74}

JavaScript/TypeScript SDK

Using the Karrio SDK to access events:

1import { useEvents, useEvent } from '@karrio/hooks';
2
3// Query events with filtering
4const EventsComponent = () => {
5  const { query, filter, setFilter } = useEvents({
6    type: ['shipment.created', 'tracking.status_updated'],
7    offset: 0,
8    first: 20
9  });
10
11  if (query.isLoading) return <div>Loading events...</div>;
12  if (query.error) return <div>Error loading events</div>;
13
14  return (
15    <div>
16      <h3>System Events</h3>
17      {query.data?.events.edges.map(({ node: event }) => (
18        <div key={event.id}>
19          <p>{event.type} - {event.created_at}</p>
20          <p>Test mode: {event.test_mode ? 'Yes' : 'No'}</p>
21          <p>Pending webhooks: {event.pending_webhooks}</p>
22          <pre>{JSON.stringify(event.data, null, 2)}</pre>
23        </div>
24      ))}
25    </div>
26  );
27};
28
29// Get single event
30const EventDetailComponent = ({ eventId }) => {
31  const { query } = useEvent(eventId);
32
33  if (query.isLoading) return <div>Loading event...</div>;
34  if (query.error) return <div>Error loading event</div>;
35
36  const event = query.data?.event;
37
38  return (
39    <div>
40      <h3>Event Details</h3>
41      <p>ID: {event?.id}</p>
42      <p>Type: {event?.type}</p>
43      <p>Created: {event?.created_at}</p>
44      <p>Test mode: {event?.test_mode ? 'Yes' : 'No'}</p>
45      <pre>{JSON.stringify(event?.data, null, 2)}</pre>
46    </div>
47  );
48};

Event Types & Structure

Events in Karrio follow a standardized structure with event-specific data payloads. All events include the same base fields with type-specific data:

Common Event Structure

1{
2  "id": "evt_unique_identifier",
3  "type": "event.type",
4  "data": {
5    // Event-specific data payload
6  },
7  "test_mode": false,
8  "pending_webhooks": 0,
9  "created_at": "2024-01-15T10:30:00Z"
10}

Available Event Types

Based on the Karrio event system, the following event types are supported:

shipment.created: When a new shipment is created
shipment.updated: When shipment details are modified
shipment.cancelled: When a shipment is cancelled
tracking.updated: When tracking information changes
order.created: When a new order is created
order.fulfilled: When an order is marked as fulfilled
webhook.delivered: When a webhook is successfully delivered
webhook.failed: When webhook delivery fails

Real-Time Event Processing

Event-Driven Workflows

Build reactive systems that respond immediately to shipping events:

Event-driven order fulfillment
1class EventDrivenFulfillment {
2  async handleShipmentCreated(event) {
3    const { shipment } = event.data;
4
5    // Update order status
6    await this.updateOrderStatus(shipment.reference, "shipped");
7
8    // Notify customer
9    await this.sendShippingNotification(shipment);
10
11    // Update inventory
12    await this.decrementInventory(shipment.line_items);
13  }
14
15  async handleTrackingUpdated(event) {
16    const { tracking } = event.data;
17
18    if (tracking.status === "delivered") {
19      // Complete order
20      await this.completeOrder(tracking.reference);
21
22      // Request review
23      await this.requestCustomerReview(tracking.recipient);
24
25      // Analytics tracking
26      await this.trackDeliveryMetrics(tracking);
27    }
28  }
29}

Event Correlation

Track related events across the system:

Correlate events across shipment lifecycle
1class EventCorrelator {
2  async trackShipmentJourney(shipmentId) {
3    const events = await this.getShipmentEvents(shipmentId);
4
5    const journey = events.reduce((timeline, event) => {
6      timeline.push({
7        timestamp: event.created_at,
8        type: event.type,
9        status: this.extractStatus(event),
10        location: this.extractLocation(event)
11      });
12      return timeline;
13    }, []);
14
15    return {
16      shipment_id: shipmentId,
17      timeline: journey.sort((a, b) =>
18        new Date(a.timestamp) - new Date(b.timestamp)
19      ),
20      current_status: journey[journey.length - 1]?.status,
21      total_events: events.length
22    };
23  }
24}
25```
26
27## Use Cases
28
29### Real-Time Order Management
30
31Build responsive order management systems that react instantly to shipping events:
32
33- **Automated Status Updates**: Update order status immediately when shipments are created or tracking changes
34- **Customer Notifications**: Send real-time shipping notifications and delivery updates
35- **Inventory Management**: Automatically adjust inventory when shipments are created or cancelled
36- **Analytics & Reporting**: Track shipping performance and customer satisfaction metrics
37
38### Integration & Automation
39
40Connect Karrio events to external systems and automation workflows:
41
42- **ERP Integration**: Sync shipping data with enterprise resource planning systems
43- **CRM Updates**: Update customer records with shipping and delivery information
44- **Webhook Triggering**: Trigger external webhooks and API calls based on events
45- **Business Intelligence**: Stream events to analytics platforms for reporting
46
47### Monitoring & Alerting
48
49Monitor your shipping operations with real-time event streams:
50
51- **Exception Handling**: Alert on failed shipments, delivery issues, or API errors
52- **Performance Monitoring**: Track response times and system performance
53- **Compliance Auditing**: Maintain audit trails for regulatory compliance
54- **Operational Dashboards**: Build real-time dashboards showing shipping metrics
55
56## Getting Started
57
58Ready to implement real-time event processing with Karrio? Follow these steps:
59
601. **Set up event subscriptions** using GraphQL queries for your needed event types
612. **Configure webhooks** for real-time event delivery to your applications
623. **Implement event handlers** to process events and trigger business logic
634. **Build monitoring dashboards** to track event streams and system health
64
65### Next Steps
66
67- Learn about [webhooks](/docs/products/webhooks) for event delivery and automation
68- Explore [workflows](/docs/products/workflows) for event-driven automation
69- Set up [admin console](/docs/products/admin-console) for event management
70- Configure [api logs](/docs/products/api-logs) for comprehensive system monitoring
71
72### Real-Time Customer Notifications
73
74Perfect for e-commerce and customer-facing applications:
75
76- **Shipping Confirmations**: Instant notifications when labels are purchased
77- **Delivery Updates**: Real-time tracking status updates to customers
78- **Exception Handling**: Proactive customer service for delivery issues
79- **Order Lifecycle**: Complete order-to-delivery communication
80
81### System Integration
82
83Designed for enterprise and platform integrations:
84
85- **ERP Synchronization**: Keep enterprise systems in sync with shipping status
86- **Inventory Management**: Update stock levels based on fulfillment events
87- **Analytics & Reporting**: Real-time data feeds for business intelligence
88- **Workflow Automation**: Trigger business processes based on shipping events
89
90### Monitoring & Operations
91
92Built for DevOps and operational teams:
93
94- **System Health Monitoring**: Track platform performance and carrier status
95- **Alert Management**: Real-time alerts for system issues and exceptions
96- **Audit & Compliance**: Complete audit trails for regulatory requirements
97- **Performance Analytics**: Monitor shipping performance and SLA compliance
98
99## Getting Started
100
101Ready to build event-driven shipping applications with Karrio? Follow these steps:
102
1031. **Subscribe to events** you need to monitor in your application
1042. **Implement event handlers** to process events and trigger actions
1053. **Set up event streaming** for real-time processing
1064. **Build event aggregation** for analytics and reporting
107
108### Next Steps
109
110- Learn about [webhooks](/docs/products/webhooks) for HTTP-based event delivery
111- Explore [api logs](/docs/products/api-logs) for detailed event monitoring
112- Set up [workflows](/docs/products/workflows) for event-driven automation
113- Configure [admin console](/docs/products/admin-console) for event management

Product Guides

Control Plane

Developer Tools

Events & Real-Time Streaming

Features

Real-Time Event Processing

Event Streaming

Complete Event History

Custom Event Handlers

Advanced Event Filtering

Additional features

Data Flow

Event-Driven Architecture

API Reference

GraphQL API

Query Events

Get Single Event

JavaScript/TypeScript SDK

Event Types & Structure

Common Event Structure

Available Event Types

Real-Time Event Processing

Event-Driven Workflows

Event Correlation