HTTP Webhooks

HTTP Push using Webhooks

HTTP webhooks provide a simple and reliable way to receive real-time IoT data from Globe Tracker devices. When events occur, our system sends HTTP POST requests to your specified endpoint with the event data.

Setup Requirements

To receive webhook notifications, you need:

A publicly accessible HTTPS endpoint
Valid SSL certificate for your endpoint
Authentication credentials (to be provided to Globe Tracker)
Ability to respond with appropriate HTTP status codes
Support for JSON request and response payloads

Webhook Configuration

Base URL Configuration

You need to provde a base URL for the pushes. All object types can be sent to the same endpoint but it is also possible to have distinct endpoints per object type.

Rate Limiting Configuration

We support rate limiting to help protect your webhook endpoint from being overwhelmed. This can be configured in two ways:

Standard Rate Limit Headers

We respect standard rate limit response headers from your webhook:

Retry-After: 60               # Seconds to wait before retrying (when rate limited)

When your endpoint is rate limited, you can return:

HTTP status code 429 (Too Many Requests)
Retry-After header indicating when to retry

Example rate limit response:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "error": "Rate limit exceeded. Please try again later."
}

We will honor the Retry-After header and pause deliveries for the specified duration.

Configurable Delivery Rates

We can also configure fixed delivery rates for your webhook:

Maximum items per minute
Maximum concurrent requests
Custom batch sizes

Contact us to configure these limits based on your webhook’s capacity. This helps prevent overwhelming your endpoint while ensuring reliable data delivery.

Authentication

You must provide us with your preferred authentication method and credentials. We support several authentication methods, the most common are:

API Key

Using an API key in the Authorization header:

Authorization: Bearer <your-api-key>

OAuth 2.0

Using an OAuth 2.0 bearer token:

Authorization: Bearer <oauth-token>

Custom Authentication

We also support custom authentication methods. Some examples include:

Custom header-based authentication
Basic authentication

To set up authentication:

Choose your preferred authentication method
Provide us with the necessary credentials or configuration
We will configure our webhook system to use your authentication method

We recommend using either API Key or OAuth 2.0 authentication methods.

Content Type Headers

All webhook requests use JSON:

Content-Type: application/json

Object Types

Push services send objects from object-sync services. The following object types are defined in the Object Sync OpenAPI Specification:

Asset

Represents an asset in the system.

Required fields:

id (string): Unique identifier for the asset (global_id)
name (string): Asset name/serial number
ownerId (string): Owner/customer global ID
whenCreated (string, date-time): ISO 8601 timestamp when the asset was created
whenUpdated (string, date-time): ISO 8601 timestamp when the asset was last updated

Optional fields:

boxId (string, nullable): Box global ID
disabled (boolean): Whether the asset is disabled
note (string, nullable): Optional note about the asset
tags (array of strings, nullable): Array of customer tags associated with the asset

Location

Represents a GPS location record.

Required fields:

id (integer, int64): Unique identifier for the location record
assetId (string): Asset global ID
ownerId (string): Owner/customer global ID
whenCreated (string, date-time): ISO 8601 timestamp when the location was recorded (GPS time)
latitude (number, double): GPS latitude coordinate
longitude (number, double): GPS longitude coordinate

Optional fields:

altitude (number, double, nullable): GPS altitude in meters
speed (number, double, nullable): Speed in the unit configured for the asset
heading (number, double, nullable): Heading/bearing in degrees (0-360)
zoneId (string, nullable): Zone identifier where the location was recorded

SensorData

Represents sensor data from an asset.

Required fields:

id (integer, int64): Unique identifier for the sensor data record
assetId (string): Asset global ID
ownerId (string): Owner/customer global ID
sensorId (string): Sensor identifier
sensorType (string): Type of sensor
whenCreated (string, date-time): ISO 8601 timestamp when the sensor data was recorded
value (string): Sensor value (can be string representation of number or text)
type (string): Data type of the sensor value

Optional fields:

when_received (integer, int64, nullable): Unix timestamp in milliseconds when the data was received

ReeferData

Represents reefer (refrigerated container) data.

Required fields:

id (integer, int64): Unique identifier for the reefer data record
assetId (string): Asset global ID
ownerId (string): Owner/customer global ID
whenCreated (string, date-time): ISO 8601 timestamp when the reefer data was recorded
reeferClass (string): Class/type of reefer unit
data (object): JSON object containing reefer-specific data payload (additionalProperties: true)

GensetData

Represents generator set (genset) data.

Required fields:

id (integer, int64): Unique identifier for the genset data record
assetId (string): Asset global ID
ownerId (string): Owner/customer global ID
whenCreated (string, date-time): ISO 8601 timestamp when the genset data was recorded
gensetType (string): Type/model of genset
data (object): JSON object containing genset-specific data payload (additionalProperties: true)

Optional fields:

boxId (string, nullable): Box global ID

GtoemData

Represents GTOEM (Globetracker OEM) data.

Required fields:

id (integer, int64): Unique identifier for the GTOEM data record
assetId (string): Asset global ID
ownerId (string): Owner/customer global ID
whenCreated (string, date-time): ISO 8601 timestamp when the GTOEM data was created
payloadType (integer, int32): Type identifier for the payload
data (object): JSON object containing GTOEM-specific data payload (additionalProperties: true)

Optional fields:

boxId (string, nullable): Box global ID
when_received (integer, int64, nullable): Unix timestamp in milliseconds when the data was received

For complete schema definitions, you can download the full OpenAPI schema file for use in API documentation tools, code generation, or validation.

Additional Fields

Push services may add additional fields to the object-sync service objects in some cases. These fields are added by the push service infrastructure and are not part of the base object schema.

HTTP Push

HTTP push can optionally inject an eventId field into the payload when configured:

Configuration: Set INJECT_EVENT_ID=true and specify INJECT_EVENT_ID_PATH to control where the eventId is injected
Field: eventId (string, UUID) - The unique event identifier from the Flowcore event system
Location: The eventId is injected at the path specified by INJECT_EVENT_ID_PATH (e.g., metadata.sourceEventId)

Example with eventId injection:

{
  "id": 12345,
  "assetId": "550e8400-e29b-41d4-a716-446655440000",
  "ownerId": "660e8400-e29b-41d4-a716-446655440001",
  "whenCreated": "2024-03-20T14:30:00Z",
  "latitude": 55.676098,
  "longitude": 12.568337,
  "metadata": {
    "sourceEventId": "evt_550e8400-e29b-41d4-a716-446655440000"
  }
}

Note: The eventId injection is optional and must be explicitly configured. Contact your Globe Tracker representative to enable this feature.

Delivery Modes

Our webhook system supports two delivery modes:

Single Event Delivery

Individual events are sent as single JSON objects. The payload contains the object from the object-sync service directly:

Example: Location object

{
  "id": 12345,
  "assetId": "550e8400-e29b-41d4-a716-446655440000",
  "ownerId": "660e8400-e29b-41d4-a716-446655440001",
  "whenCreated": "2024-03-20T14:30:00Z",
  "latitude": 55.676098,
  "longitude": 12.568337,
  "altitude": 10.5,
  "speed": 0,
  "heading": 90
}

Example: Asset object

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "ASSET-001",
  "ownerId": "660e8400-e29b-41d4-a716-446655440001",
  "whenCreated": "2024-01-15T10:30:00Z",
  "whenUpdated": "2024-03-20T14:30:00Z",
  "disabled": false,
  "tags": ["warehouse", "priority"]
}

Batch Event Delivery

Multiple events can be sent as an array if your webhook endpoint supports batch processing. Each item in the array is an object from the object-sync service:

[
  {
    "id": 12345,
    "assetId": "550e8400-e29b-41d4-a716-446655440000",
    "ownerId": "660e8400-e29b-41d4-a716-446655440001",
    "whenCreated": "2024-03-20T14:30:00Z",
    "latitude": 55.676098,
    "longitude": 12.568337
  },
  {
    "id": 12346,
    "assetId": "550e8400-e29b-41d4-a716-446655440000",
    "ownerId": "660e8400-e29b-41d4-a716-446655440001",
    "sensorId": "sensor-001",
    "sensorType": "temperature",
    "whenCreated": "2024-03-20T14:30:01Z",
    "value": "5.2",
    "type": "DECIMAL"
  }
]

Response Format

Response Requirements

Minimum Requirement: A success HTTP status code (2xx)
Content Type: If sending content, use application/json
Response Body: Optional

Optional Response Format

If you choose to send a response body, you can include a receipt ID that we’ll store for reference:

{
  "success": true,
  "id": "your-system-reference-id"  // Optional receipt ID
}

Note: The response body is entirely optional. A simple HTTP 200 status code is sufficient for successful webhook delivery.

Response Handling

Success Response

Your endpoint must return a success HTTP status code (2xx) to acknowledge receipt of the webhook. Upon receiving a success response:

What We Store:

Success status
HTTP status code
Receipt ID (if provided in response)
Timestamp of successful delivery

Note: For successful deliveries, we do not store the full response body unless a receipt ID is included, when this is the case we save the receipt itself.

Error Response Handling

We categorize error responses into three types:

Rate Limit Errors (429)

Status code 429 indicates the webhook endpoint is rate limited:

Delivery will be paused for the duration specified in the Retry-After header
If no Retry-After header is present, we will use our default backoff strategy
The event remains in the retry queue
Rate limit metadata is stored for monitoring

Retryable Errors (5xx)

Status codes in the 5xx range indicate server errors and will trigger our retry mechanism:

We will attempt to redeliver the webhook
The event remains marked for retry in our system
Full error response content is stored for debugging

Non-Retryable Errors (4xx, excluding 429)

Status codes in the 4xx range (except 429) indicate client errors and will:

Not trigger any retry attempts
Mark the event as failed in our system
Stop any further delivery attempts
Full error response content is stored for debugging

What We Store for Errors:

Error status
HTTP status code
HTTP Response Headers
Complete response body
Error timestamp
Any additional error details provided

Request Metadata and Monitoring

Stored Metadata

For each webhook delivery attempt, we store detailed metadata including:

Timestamp of the attempt
Response status code
Response time
Customer receipt ID (if provided)
Success/failure status
Error details (if any)

Accessing Delivery History

You can access webhook delivery history and logs in several ways:

Using the Flowcore CLI

To extract push logs for the last day:

flowcore stream https://flowcore.io/globe-tracker-aps/example-data/push-results.0/created.0.stream \
  --no-live \
  -s 1d \
  --payload \
  --json

Command options:

--no-live: Get historical data only
-s 1d: Get data for the last day
--payload: Include only the payload and not Flowcore metadata
--json: Output in JSON format

You can adjust the time window using the -s flag (e.g., 12h for 12 hours, 7d for 7 days).

Using data-pump sdk

You can use the data-pump NPM package to retrieve results

Using the Dashboard

We provide a webhook dashboard where you can:

View webhook delivery history
Check delivery status and response codes
Inspect payload contents for errors
Track retry attempts and final delivery status
View stored receipt IDs and response metadata
Monitor rate limiting and performance metrics

Get in touch with you Globe Tracker representative to get access to your dashboard.

Best Practices

Quick Response: Return a 2xx response promptly (ideally within 1 second)
Asynchronous Processing: Handle time-consuming operations after sending the response
Idempotency: Implement idempotent processing to handle potential duplicate deliveries
Response Time Monitoring: Keep response times under 1 second to prevent timeouts
Error Status Codes: Use appropriate HTTP status codes to indicate success or failure:
- 200/201: Successful receipt and processing
- 4xx: Client errors (no retry)
- 5xx: Server errors (will retry)
Batch Processing: If your system can handle it, enable batch processing for better performance
Rate Limiting:
- Implement rate limit headers if your endpoint has specific capacity constraints
- Contact us to configure delivery rates that match your system’s capacity
- Consider batch processing to optimize delivery rates

Testing Webhooks

You can use our test endpoint to verify your webhook setup:

curl -X POST https://api.globetracker.com/v1/webhooks/test \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-endpoint.com/webhook"}'

Monitoring and Debugging

We provide a webhook dashboard where you can:

View webhook delivery history
Check delivery status and response codes
Inspect payload contents
Track retry attempts and final delivery status
View stored receipt IDs and response metadata