Webhooks

Overview #

Webhooks allow your application to receive real-time HTTP notifications when events occur in Trackberry. Instead of polling the API, you register a URL and Trackberry sends a POST request whenever something happens.

Setting Up Webhooks #

1. Navigate to Settings in your organization
2. Find the Webhooks section
3. Click Add Webhook Endpoint
4. Enter your endpoint URL (must be HTTPS)
5. Select the events you want to receive
6. Click Save

Event Types #

Payload Format #

All webhook payloads follow the same structure:

{
  "event": "shipment.approved",
  "timestamp": "2026-02-11T09:15:00Z",
  "data": {
    "shipment": {
      "id": "ship_abc123",
      "reference": "BU-1341",
      "status": "approved",
      "pallets_count": 42
    }
  }
}

Verifying Webhook Signatures #

Every webhook request includes a signature header to verify authenticity:

X-Trackberry-Signature: sha256=abc123...

Verify the signature using your webhook secret:

require "openssl"

def verify_signature(payload, signature, secret)
  expected = "sha256=" + OpenSSL::HMAC.hexdigest("SHA256", secret, payload)
  Rack::Utils.secure_compare(expected, signature)
end

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Retry Policy #

If your endpoint returns a non-2xx status code, Trackberry retries with exponential backoff:

After 5 failed attempts, the webhook is marked as failing and you'll receive an email notification.

Best Practices #

• Respond quickly — Return a 200 status within 5 seconds. Process the event asynchronously if needed.
• Handle duplicates — Webhooks may be delivered more than once. Use the event ID for idempotency.
• Verify signatures — Always validate the X-Trackberry-Signature header.
• Use HTTPS — Webhook endpoints must use HTTPS for security.