Webhooks

Available Events

• rate.updated: Market rate changes for watched lanes
• quote.created: New quote generated
• quote.updated: Quote status changed
• quote.expired: Quote has expired
• market.alert: Significant market changes detected

Webhook Format

All webhook payloads follow this format:

{
  "event": "rate.updated",
  "timestamp": "2024-01-20T12:00:00Z",
  "data": {
    "lane": {
      "origin": "Los Angeles",
      "destination": "Fontana"
    },
    "changes": {
      "old_rate": 525.0,
      "new_rate": 550.0,
      "percentage_change": 4.76
    }
  }
}

Setting Up Webhooks

Configure webhook endpoints through the API:

POST /v1/webhooks

Request Body

{
  "url": "https://your-domain.com/webhook",
  "events": ["rate.updated", "quote.created"],
  "secret": "your_signing_secret"
}

Security

Webhooks are signed using HMAC-SHA256:

1. Look for the X-Drayrates-Signature header
2. Verify the signature using your webhook secret
3. Validate the timestamp to prevent replay attacks

Example verification in Node.js:

const crypto = require('crypto');

const signature = req.headers['x-drayrates-signature'];
const payload = req.rawBody;
const secret = 'your_signing_secret';

const hmac = crypto.createHmac('sha256', secret);
const digest = hmac.update(payload).digest('hex');

if (signature === digest) {
  // Webhook is valid
}