Webhooks

Overview

Webhooks let you receive real-time HTTP notifications when events happen in your FreightCake account — like when a shipment is delivered or an invoice is created.

Setting Up Webhooks

1. Create an endpoint

curl -X POST https://api.freightcake.com/api/v1/webhook_endpoints \
  -H "Authorization: Bearer fk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/freightcake",
    "events": ["shipment.delivered", "invoice.created"],
    "description": "Production webhook"
  }'

2. Handle events

Your endpoint should return a 2xx status code within 30 seconds. The webhook payload:

{
  "id": "evt_abc123",
  "type": "shipment.delivered",
  "created_at": "2025-07-01T12:00:00.000Z",
  "data": {
    "shipment_id": 42,
    "pro_number": "123456789"
  }
}

3. Verify signatures

Each webhook includes an X-FreightCake-Signature header for verification. Validate this to ensure the request came from FreightCake.

Event Types

Shipment Events

Event	Description
`shipment.booked`	Shipment has been booked with carrier
`shipment.picked_up`	Carrier picked up the freight
`shipment.in_transit`	Shipment is in transit
`shipment.out_for_delivery`	Shipment is out for delivery
`shipment.delivered`	Shipment has been delivered
`shipment.exception`	Delivery exception occurred
`shipment.cancelled`	Shipment was cancelled or voided

Quote Events

Event	Description
`quote.created`	New rate quotes generated
`quote.expired`	Quote has expired

Invoice Events

Event	Description
`invoice.created`	New invoice generated
`invoice.paid`	Invoice payment received
`invoice.overdue`	Invoice is past due

BOL Events

Event	Description
`bol.generated`	Bill of lading PDF generated

Retry Policy

Failed deliveries are retried with exponential backoff:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours
6	8 hours
7	24 hours

After 7 attempts, the delivery is marked as failed.

Managing Endpoints

List endpoints

curl https://api.freightcake.com/api/v1/webhook_endpoints \
  -H "Authorization: Bearer fk_live_your_key_here"

Update an endpoint

curl -X PATCH https://api.freightcake.com/api/v1/webhook_endpoints/1 \
  -H "Authorization: Bearer fk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "events": ["shipment.delivered", "shipment.exception", "invoice.created"] }'

Test an endpoint

Send a test event to verify your endpoint is working:

curl -X POST https://api.freightcake.com/api/v1/webhook_endpoints/1/test \
  -H "Authorization: Bearer fk_live_your_key_here"

View deliveries

Check recent delivery attempts for an endpoint:

curl https://api.freightcake.com/api/v1/webhook_endpoints/1/deliveries \
  -H "Authorization: Bearer fk_live_your_key_here"

Delete an endpoint

curl -X DELETE https://api.freightcake.com/api/v1/webhook_endpoints/1 \
  -H "Authorization: Bearer fk_live_your_key_here"

On this page