Webhooks

Setting Up Webhooks

1. Create an endpoint

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

The create response includes secret once. Store it in your secret manager. List, retrieve, and update responses never include it.

2. Handle events

Your endpoint must return a 2xx status code within 10 seconds. Process slow work asynchronously. The webhook payload is:

{
  "id": "evt_abc123",
  "type": "shipment.delivered",
  "created": "2026-07-01T12:00:00.000Z",
  "data": {
    "shipment": {
      "id": 42,
      "proNumber": "123456789",
      "status": "DELIVERED",
      "location": "Atlanta, GA",
      "carrier": "Sandbox Freight Co"
    }
  },
  "webhook": {
    "id": "whk_1",
    "url": "https://your-app.com/webhooks/freightcake"
  }
}

Each request includes X-FreightCake-Signature: t={timestamp},v1={hex}. Verify the unmodified request body before parsing JSON. The SDK rejects signatures more than 5 minutes from the current time by default.

import { verifyWebhookSignature } from '@freightcake/sdk'

export async function POST(request: Request) {
  const rawBody = await request.text()
  const signature = request.headers.get('x-freightcake-signature')
  if (!signature) return new Response('Missing signature', { status: 401 })

  try {
    verifyWebhookSignature(
      rawBody,
      signature,
      process.env.FREIGHTCAKE_WEBHOOK_SECRET!,
    )
  } catch {
    return new Response('Invalid signature', { status: 401 })
  }

  const event = JSON.parse(rawBody)
  await enqueueEvent(event)
  return new Response('ok')
}

Pass { tolerance: 600 } as the fourth argument only when your receiver needs a wider replay window.

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.updated`	Invoice fields changed
`invoice.paid`	Invoice payment received
`invoice.voided`	Invoice was voided
`invoice.overdue`	Invoice is past due

Customer Events

Event	Description
`customer.created`	Customer was created
`customer.updated`	Customer fields changed

Carrier Bill Events

Event	Description
`bill.created`	Carrier bill was created
`bill.updated`	Carrier bill fields changed

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	12 hours
7	24 hours

After 7 attempts, the delivery is marked as failed. After 10 consecutive failed attempts across deliveries, FreightCake disables the endpoint and emails its owner. Rotate the secret only when the endpoint reports Signing secret rotation required; fix receiver availability before re-enabling other disabled endpoints.

Managing Endpoints

List endpoints

curl https://api.freightcake.com/api/v1/webhooks \
  -H "Authorization: Bearer fk_live_REPLACE_WITH_YOUR_KEY"

Update an endpoint

curl -X PATCH https://api.freightcake.com/api/v1/webhooks/1 \
  -H "Authorization: Bearer fk_live_REPLACE_WITH_YOUR_KEY" \
  -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/webhooks/1/test \
  -H "Authorization: Bearer fk_live_REPLACE_WITH_YOUR_KEY"

This queues a signed webhook.test event for that endpoint only.

Rotate a signing secret

curl -X POST https://api.freightcake.com/api/v1/webhooks/1/rotate-secret \
  -H "Authorization: Bearer fk_live_REPLACE_WITH_YOUR_KEY" \
  -H "Idempotency-Key: rotate-webhook-1-2026-07-10"

Save the returned secret before discarding the response. See Webhook Endpoints for the response shape and SDK method.

View deliveries

Check recent delivery attempts for an endpoint:

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

Delete an endpoint

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

Overview