Webhook Endpoints

Create Endpoint

POST /api/v1/webhooks

Request Body

Field	Type	Required	Description
`url`	string	Yes	HTTPS URL to receive events
`events`	string[]	Yes	Supported event types
`description`	string	No	Human-readable description

Example

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",
    "events": ["shipment.delivered", "invoice.created"]
  }'

Response

{
  "object": "webhook_endpoint",
  "id": 1,
  "url": "https://your-app.com/webhooks",
  "events": ["shipment.delivered", "invoice.created"],
  "active": true,
  "secret_prefix": "whsec_7f4a91",
  "consecutive_failures": 0,
  "disabled_at": null,
  "disabled_reason": null,
  "created_at": "2026-07-01T00:00:00.000Z",
  "updated_at": "2026-07-01T00:00:00.000Z",
  "secret": "whsec_REPLACE_WITH_ENDPOINT_SECRET"
}

The secret field is returned only when you create or rotate an endpoint. Store it in a secret manager before discarding the response.

List Endpoints

GET /api/v1/webhooks

Return webhook endpoints for the API key's organization.

Query Parameters

Param	Type	Description
`limit`	number	Max results (1-100, default 10)
`starting_after`	string	Cursor for forward pagination

Retrieve Endpoint

GET /api/v1/webhooks/:id

Return one webhook endpoint by ID.

Update Endpoint

PATCH /api/v1/webhooks/:id

Update the receiver URL, subscriptions, description, or active state.

Request Body

Field	Type	Description
`url`	string	New endpoint URL
`events`	string[]	Updated event subscriptions
`active`	boolean	Enable/disable the endpoint
`description`	string	Updated description

Delete Endpoint

DELETE /api/v1/webhooks/:id

Delete one webhook endpoint and its delivery history.

Rotate Signing Secret

POST /api/v1/webhooks/:id/rotate-secret

Replace a compromised or unavailable signing secret. The old secret stops working immediately. Use an idempotency key so a retried request returns the same one-time 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"

{
  "object": "webhook_secret",
  "endpoint_id": 1,
  "secret": "whsec_REPLACE_WITH_ROTATED_SECRET",
  "secret_prefix": "whsec_a028c1"
}

const rotated = await freightcake.webhooks.rotateSecret('1', {
  idempotencyKey: 'rotate-webhook-1-2026-07-10',
})

await saveSecret(rotated.secret)

Test Endpoint

POST /api/v1/webhooks/:id/test

Queues one webhook.test delivery to this endpoint. The endpoint must be active and have a usable signing secret.

List Deliveries

GET /api/v1/webhooks/:id/deliveries

Return recent delivery attempts for this endpoint.

Query Parameters

Param	Type	Description
`limit`	number	Max results (1-100, default 10)
`starting_after`	string	Cursor for forward pagination
`status`	string	Filter: `pending`, `delivered`, `failed`, `retrying`

Errors

Status	When
`400`	The callback URL, event subscription, or delivery status filter is invalid
`404`	The webhook endpoint does not exist in the API key's organization
`422`	A test delivery cannot be sent to the configured endpoint

See Handle API Errors for the common error envelope and retry guidance.

On this page