Using Webhooks

Webhooks allow your application to receive real-time notifications about events in the Shipping Channels platform. This guide will help you understand how to set up, secure, and handle webhooks.

What are Webhooks?

Webhooks are HTTP callbacks that notify your application when specific events occur in the Shipping Channels platform. For example, you can receive notifications when:

• A tracking parcel status changes
• A shipping channel is created, updated, or deleted
• A shipping channel is validated or validation fails

Webhook Events

The Shipping Channels platform supports the following webhook events:

Event Type	Description
shipping_channel.created	A new shipping channel has been created
shipping_channel.updated	A shipping channel has been updated
shipping_channel.deleted	A shipping channel has been deleted
shipping_channel.validated	A shipping channel has been successfully validated
shipping_channel.status_changed	A shipping channel's status has changed
tracking_parcel.created	A new tracking parcel has been created
tracking_parcel.updated	A tracking parcel has been updated
tracking_parcel.deleted	A tracking parcel has been deleted
tracking_parcel.status_changed	A tracking parcel's status has changed
shipment.created	A new shipment has been created
shipment.updated	A shipment has been updated
shipment.deleted	A shipment has been deleted
shipment.status_changed	A shipment's status has changed

Setting Up Webhooks

To set up a webhook:

1. Create an endpoint on your server to receive webhook events
2. Register the webhook URL with Shipping Channels
3. Set up authentication to secure your webhook

Creating a Webhook Subscription

You can create a webhook subscription using the Webhook Subscriptions API or through the dashboard:

1. Log in to your Shipping Channels dashboard
2. Navigate to Settings → Webhooks
3. Click "Add Webhook"
4. Enter your webhook URL
5. Select the events you want to subscribe to
6. Optionally add a secret key for signature verification
7. Click "Create Webhook"

Receiving Webhook Events

When an event occurs, Shipping Channels will send an HTTP POST request to your webhook URL with a JSON payload containing information about the event.

Example payload for a tracking_parcel.status_changed event:

{
  "id": "evt_123456",
  "created_at": "2025-04-07T12:00:00Z",
  "type": "tracking_parcel.status_changed",
  "data": {
    "tracking_parcel": {
      "id": "tp_123456",
      "tracking_number": "1234567890",
      "shipping_channel_id": "ch_123456",
      "shipment_id": "sh_123456",
      "status": "delivered",
      "previous_status": "in_transit",
      "created_at": "2025-04-06T10:00:00Z",
      "updated_at": "2025-04-07T12:00:00Z"
    }
  }
}

Webhook Security

To verify that webhook requests come from Shipping Channels, you should:

1. Set a webhook secret when creating the webhook subscription
2. Verify the signature included in the webhook request

Verifying Webhook Signatures

Shipping Channels includes a signature in the X-Shipping-Channels-Signature header of each webhook request. The signature is a HMAC SHA-256 hash of the request body, using your webhook secret as the key.

Here's how to verify the signature:

PHP

<?php
function verifyWebhookSignature($payload, $signatureHeader, $secret) {
    $expectedSignature = hash_hmac('sha256', $payload, $secret);
    return hash_equals($expectedSignature, $signatureHeader);
}

$payload = file_get_contents('php://input');
$signatureHeader = $_SERVER['HTTP_X_SHIPPING_CHANNELS_SIGNATURE'];
$secret = 'your_webhook_secret';

if (!verifyWebhookSignature($payload, $signatureHeader, $secret)) {
    http_response_code(403);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

// Process the webhook
$event = json_decode($payload, true);

JavaScript (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(payload, signatureHeader, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(signatureHeader)
  );
}

app.post('/webhook', (req, res) => {
  const payload = JSON.stringify(req.body);
  const signatureHeader = req.headers['x-shipping-channels-signature'];
  const secret = 'your_webhook_secret';
  
  if (!verifyWebhookSignature(payload, signatureHeader, secret)) {
    return res.status(403).json({ error: 'Invalid signature' });
  }
  
  // Process the webhook
  const event = req.body;
});

Best Practices

Follow these best practices for reliable webhook processing:

1. Respond quickly: Your endpoint should acknowledge receipt of the webhook by returning a 2xx status code as quickly as possible. Process the webhook asynchronously if needed.

2. Handle retries: Shipping Channels will retry failed webhook deliveries with exponential backoff for up to 24 hours.

3. Idempotency: Process webhooks idempotently to handle potential duplicate deliveries.

4. Error handling: Implement proper error handling to ensure your webhook processing is robust.

5. Logging: Log all webhook events for debugging and auditing purposes.

6. Monitoring: Set up monitoring for your webhook endpoint to ensure it's functioning correctly.

Testing Webhooks

You can test your webhook implementation using the "Test Webhook" feature in the dashboard:

1. Log in to your Shipping Channels dashboard
2. Navigate to Settings → Webhooks
3. Select the webhook you want to test
4. Click "Test Webhook"
5. Select an event type
6. Click "Send Test Webhook"

This will send a test event to your webhook URL, allowing you to verify that your implementation is working correctly.

Webhook Logs

Shipping Channels keeps logs of all webhook delivery attempts. You can view these logs in the dashboard or using the Webhook Subscription Logs API, Get Webhook Subscription Log API, and Clear Webhook Subscription Logs API.

The logs include:

• The event that triggered the webhook
• The request payload
• The response status code and body
• The time it took to deliver the webhook
• Any errors that occurred during delivery

Troubleshooting

If you're having issues with webhooks, check the following:

1. Verify that your webhook URL is publicly accessible
2. Check that your server is not blocking or rate-limiting requests from Shipping Channels
3. Ensure your signature verification is implemented correctly
4. Check the webhook logs for delivery attempts and errors
5. Test your webhook using the "Test Webhook" feature

If you continue to have issues, contact our support team.