Webhooks

Overview

Webhooks allow you to receive real-time notifications when specific events occur in your Drayrates account. Instead of polling our API for updates, webhooks will send HTTP POST requests to your specified endpoints whenever relevant events happen.

Available Events

• chat.created: New search/chat session created
• quote.created: New quote generated
• quote.updated: Quote status or details changed
• quote.deleted: Quote has been deleted
• rfp.created: New RFP created
• rfp.updated: RFP status or details changed
• rfp.deleted: RFP has been deleted

Webhook Format

All webhook payloads follow this format:

{
  "id": "evt_1234567890",
  "event": "quote.created",
  "created": "2024-03-20T15:30:00Z",
  "object": {
    // Event-specific data
  },
  "livemode": true
}

Event-Specific Data Examples

Quote Events

{
  "id": "evt_1234567890",
  "event": "quote.created",
  "created": "2024-03-20T15:30:00Z",
  "object": {
    "quoteNumber": "DRQ-2024-1234",
    "status": "pending",
    "type": "single-lane",
    "baseRate": 448,
    "customerRate": 654,
    "margin": 46,
    "confidenceScore": 97,
    "transitTime": "58 mins",
    "distance": 33,
    "fscIncluded": true,
    "fscRate": 0,
    "fscAmount": 0,
    "dieselPrice": 4.259,
    "dieselRegion": "West Coast (PADD5)",
    "accessorialsType": "default",
    "accessorials": [
      {
        "name": "Pre-Pull",
        "rate": 150,
        "id": "pre-pull",
        "type": "default",
        "frequency": "per container"
      },
      {
        "name": "Chassis",
        "rate": 40,
        "id": "chassis",
        "type": "default",
        "frequency": "per day"
      }
    ],
    "volumeDiscounts": [
      {
        "discount": 10.5,
        "containers": 10
      },
      {
        "discount": 8.5,
        "containers": 20
      }
    ],
    "route": {
      "origin": "Port of LA/Long Beach",
      "destination": "Echo Park, CA",
      "originType": "marine",
      "destinationType": "city",
      "coordinates": {
        "origin": {
          "lat": 33.7220726,
          "lng": -118.2531463
        },
        "destination": {
          "lat": 34.0780857,
          "lng": -118.2604694
        }
      }
    },
    "searchParams": {
      "quoteType": "spot",
      "deliveryType": "live",
      "containerVolume": "",
      "volumeDiscount": 0
    },
    "validUntil": {
      "seconds": 1743692330,
      "nanoseconds": 117000000
    }
  },
  "livemode": true
}

Setting Up Webhooks

Configure webhook endpoints through our API:

POST /v1/webhooks

Request Body

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

Response

{
  "status": "success",
  "data": {
    "id": "webhook_id",
    "url": "https://your-domain.com/webhook",
    "events": ["quote.created", "quote.updated"],
    "orgId": "your_organization_id"
  }
}

Managing Webhooks

Update Webhook Events

PUT /v1/webhooks/{webhook_id}

Request body:

{
  "events": ["quote.created", "quote.updated", "quote.deleted"],
  "orgId": "your_organization_id"
}

Delete Webhook

DELETE /v1/webhooks/{webhook_id}

Webhook Delivery

Headers

Each webhook request includes the following headers:

• Content-Type: application/json
• X-Event-Id: Unique identifier for the webhook event

Retry Logic

Our system implements automatic retry logic for failed webhook deliveries:

1. Webhooks are marked as "pending" when first created
2. Multiple retry attempts are made for failed deliveries
3. Each attempt is logged with response status and timestamp
4. Webhooks are marked as "delivered" or "failed" based on the delivery outcome

Monitoring Webhook Status

You can monitor webhook delivery status through our API or dashboard. Each webhook event includes:

• Event ID
• Delivery status
• Number of attempts
• Timestamp of last attempt
• Response details for each attempt

Best Practices

1. Implement Idempotency
   • Use the X-Event-Id header to prevent duplicate processing
   • Store processed event IDs to avoid duplicates
2. Quick Response
   • Respond quickly to webhook requests (within 5 seconds)
   • Process webhooks asynchronously if needed
   • Return 2xx status code to acknowledge receipt
3. Error Handling
   • Implement proper error handling
   • Log failed webhook requests
   • Set up monitoring for webhook failures
4. Security
   • Use HTTPS endpoints only
   • Validate the webhook source
   • Implement request timeout handling

Error Handling

Common webhook delivery errors:

Rate Limits

• Maximum of 100 concurrent webhook deliveries per organization
• Retry attempts are limited to 5 per webhook
• Minimum 5-minute interval between retry attempts

Testing Webhooks

1. Set up a test endpoint (e.g., using webhook.site)
2. Subscribe to test events
3. Trigger test events through our API
4. Monitor webhook delivery in real-time

Support

For webhook-related support:

• Email: support@drayrates.ai
• Documentation: https://drayrates.ai/resources/api