Register webhook endpoint

Register a new webhook endpoint to receive real-time notifications about shipping events.

Overview

Webhooks allow you to receive real-time updates about shipping events directly to your application. When events occur in your Teleship account, we’ll send HTTP POST requests to your webhook endpoint with event data.

How it works

1. Register your endpoint - Provide your URL and select which events to subscribe to
2. Receive events - Teleship sends HTTP POST requests to your endpoint when events occur
3. Verify signatures - Use the webhook secret to verify requests come from Teleship
4. Process events - Handle the event data in your application

Payload Structure

All webhook payloads follow a consistent structure:

{
  "eventName": "label.generated",
  "objectType": "shipment",
  "objectId": "6f384ad7-f8bf-40ce-8bf0-715248738f10",
  "data": {
    // Event-specific data (see examples below)
  }
}

Payload Fields

• eventName: The type of event that occurred (e.g., “label.generated”, “shipment.updated”)
• objectType: The type of object this event relates to (e.g., “shipment”, “manifest”)
• objectId: The unique identifier of the object (e.g., shipment ID, manifest ID)
• data: The event-specific data payload

Security & Signature Verification

Webhook Secret

Each webhook endpoint has a unique secret that’s only returned when you create the webhook. This secret is used to verify that webhook requests come from Teleship.

Important: The secret remains the same for the lifetime of the webhook unless you regenerate it.

Signature Header

Teleship includes a signature in the x-teleship-signature header with every webhook request. Verify this signature to ensure the request is authentic:

// Example signature verification
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Event Types

Available Events

• *: Subscribe to all events (default)
• label.generated: When a shipping label is created
• shipment.updated: When shipment status or details change
• manifest.created: When a manifest is created
• document.uploaded: When documents are uploaded

Event Data Structure

The data field contains event-specific information. For shipment events, this includes:

{
  "status": "label_created",
  "shipmentId": "6f384ad7-f8bf-40ce-8bf0-715248738f10",
  "trackingNumber": "TSGBUSA54UHK092337564",
  "customerReference": "#1001",
  "shipDate": "2025-06-30T22:36:22.843Z",
  "estimatedDelivery": "2025-07-08T06:59:59.999Z",
  "events": [
    {
      "timestamp": "2025-06-30T22:26:25.201Z",
      "code": "S_102",
      "description": "Shipment info received by carrier",
      "location": "London, UK"
    }
  ],
  "shipFrom": {
    "name": "London Store",
    "company": "TELESHIP LIMITED",
    "address": {
      "line1": "Flat 4, 24 Upper Tachbrook Street",
      "city": "London",
      "state": "England",
      "country": "GB",
      "postcode": "SW1V 1SW"
    }
  },
  "shipTo": {
    "name": "Fanny Dadin",
    "email": "fanny@teleship.com",
    "phone": "+1 213-601-6000",
    "address": {
      "line1": "1300 Eunice Avenue",
      "city": "Los Angeles",
      "state": "CA",
      "country": "US",
      "postcode": "90001"
    }
  },
  "firstMile": {
    "carrier": "DHL Express",
    "trackingNumber": "1234567890",
    "trackingUrl": "https://www.dhl.com/track/1234567890"
  },
  "lastMile": {
    "carrier": "USPS",
    "trackingNumber": "9400100000000000000000",
    "trackingUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400100000000000000000"
  }
}

Important Details

Events Array

The events field is an array containing the complete event history for the shipment, not just the most recent event. Each event includes:

• timestamp: When the event occurred (UTC timezone)
• code: Event code from the carrier
• description: Human-readable event description
• location: Where the event occurred (if available)

ObjectId and ObjectType

• objectId: The unique identifier of the shipment, manifest, or other object this event relates to
• objectType: The type of object (“shipment”, “manifest”, etc.)

These fields help you identify which specific object the event relates to in your system.

Timezone

All timestamps in webhook payloads are in UTC timezone (ISO 8601 format). Convert to your local timezone as needed.

FirstMile and LastMile

The firstMile and lastMile objects contain external carrier tracking information:

• firstMile: Information about the pickup/departure carrier
• lastMile: Information about the final delivery carrier

These fields are only populated when:

• The shipment uses multiple carriers (e.g., international shipments)
• External tracking numbers are available
• The carriers provide tracking URLs

The events in the events array come from both first-mile and last-mile carriers, providing a complete picture of the shipment’s journey.

Best Practices

1. Verify signatures - Always verify the webhook signature to ensure authenticity
2. Handle duplicates - Webhooks may be sent multiple times; use event IDs to prevent duplicate processing
3. Respond quickly - Return a 2xx status code immediately, then process the event asynchronously
4. Handle failures gracefully - Implement retry logic for failed webhook processing
5. Monitor webhook health - Track webhook delivery success rates and response times

Example Implementation

// Express.js webhook handler example
app.post('/webhooks/teleship', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-teleship-signature'];
  const payload = req.body;

  // Verify signature
  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(400).send('Invalid signature');
  }

  // Parse payload
  const event = JSON.parse(payload);

  // Handle different event types
  switch (event.eventName) {
    case 'label.generated':
      handleLabelGenerated(event.data);
      break;
    case 'shipment.updated':
      handleShipmentUpdated(event.data);
      break;
    default:
      console.log('Unhandled event type:', event.eventName);
  }

  // Respond quickly
  res.status(200).send('OK');
});

Why use webhooks?

• Real-time updates: Get instant notifications when shipment status changes
• Automation: Trigger workflows based on shipping events
• Integration: Sync shipment data with your order management system
• Customer experience: Update customers with real-time tracking information