Webhook endpoints

Where Ballast sends events, and their delivery log. 7 endpoints, each also a tool for your AI through MCP. Authentication and errors are on the overview.

List webhook endpoints

GET/api/v1/webhooks

With delivery counts for the last 7 days. Signing secrets are never listed.

MCP tool list_webhooksRead-only

Returns

webhooksrequiredobject[]
eventsrequiredobject[]

cURL

curl https://ballast.to/api/v1/webhooks \
  -H "Authorization: Bearer $BALLAST_API_KEY"

Ballast POSTs JSON to the URL for each chosen event, signed with the returned secret (header Ballast-Signature: t=<unix>,v1=<HMAC-SHA256 hex of "<t>.<body>">). The secret is shown once here; reveal it later in Settings.

MCP tool create_webhookOwners and admins

Parameters

urlrequiredstring
descriptionstring
eventsrequired"lead.replied" | "lead.labeled" | "lead.bounced" | "lead.unsubscribed" | "lead.won" | "campaign.paused"[]

Returns

webhookrequiredobject
secretrequiredstring

cURL

curl -X POST https://ballast.to/api/v1/webhooks \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"<url>","events":"lead.replied"}'

Change a webhook's URL, events or on/off

PATCH/api/v1/webhooks/{id}

Turning an endpoint back on clears the failure count.

MCP tool update_webhookOwners and admins

Parameters

idrequiredpath · string
urlstring
descriptionstring | null
events"lead.replied" | "lead.labeled" | "lead.bounced" | "lead.unsubscribed" | "lead.won" | "campaign.paused"[]
enabledboolean

Returns

idrequiredstring
urlrequiredstring
descriptionrequiredstring | null
eventsrequired"lead.replied" | "lead.labeled" | "lead.bounced" | "lead.unsubscribed" | "lead.won" | "campaign.paused"[]
enabledrequiredboolean
disabledReasonrequiredstring | null: Why Ballast turned it off, when it did
lastDeliveryAtrequiredstring | null
lastStatusrequirednumber | null: HTTP status of the last attempt, 0 when the endpoint didn't answer
deliveredrequirednumber
failedrequirednumber
pendingrequirednumber
createdAtrequiredstring

cURL

curl -X PATCH https://ballast.to/api/v1/webhooks/<id> \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"<url>","description":{}}'

Remove a webhook endpoint

DELETE/api/v1/webhooks/{id}

Pending deliveries to it are dropped.

MCP tool delete_webhookOwners and adminsMCP asks to confirm

Parameters

idrequiredpath · string

Returns

okrequiredtrue

cURL

curl -X DELETE https://ballast.to/api/v1/webhooks/<id> \
  -H "Authorization: Bearer $BALLAST_API_KEY"

Send a test event now

POST/api/v1/webhooks/{id}/test

POSTs a signed sample lead.replied event (marked test: true) and returns the endpoint's answer. Not retried.

MCP tool test_webhookOwners and admins

Parameters

idrequiredpath · string

Returns

deliveredrequiredboolean
statusrequirednumber
errorrequiredstring | null
bodyrequiredstring
msrequirednumber

cURL

curl -X POST https://ballast.to/api/v1/webhooks/<id>/test \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Recent deliveries to an endpoint

GET/api/v1/webhooks/{id}/deliveries

Newest first, the last 30 days, with the payload as sent.

MCP tool list_webhook_deliveriesRead-only

Parameters

idrequiredpath · string
limitquery · integer

Returns

deliveriesrequiredobject[]

cURL

curl https://ballast.to/api/v1/webhooks/<id>/deliveries \
  -H "Authorization: Bearer $BALLAST_API_KEY"

Send a failed delivery again

POST/api/v1/webhooks/deliveries/{id}/redeliver

Queues it with a fresh set of retries.

Owners and admins

Parameters

idrequiredpath · string

Returns

okrequiredtrue

cURL

curl -X POST https://ballast.to/api/v1/webhooks/deliveries/<id>/redeliver \
  -H "Authorization: Bearer $BALLAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Add a webhook endpoint

POST/api/v1/webhooks

MCP tool create_webhookOwners and admins

Parameters

urlrequiredstring
descriptionstring
eventsrequired"lead.replied" | "lead.labeled" | "lead.bounced" | "lead.unsubscribed" | "lead.won" | "campaign.paused"[]

Returns

webhookrequiredobject
secretrequiredstring

Change a webhook's URL, events or on/off

PATCH/api/v1/webhooks/{id}

Turning an endpoint back on clears the failure count.

MCP tool update_webhookOwners and admins

Parameters

idrequiredpath · string
urlstring
descriptionstring | null
events"lead.replied" | "lead.labeled" | "lead.bounced" | "lead.unsubscribed" | "lead.won" | "campaign.paused"[]
enabledboolean

Returns

idrequiredstring
urlrequiredstring
descriptionrequiredstring | null
eventsrequired"lead.replied" | "lead.labeled" | "lead.bounced" | "lead.unsubscribed" | "lead.won" | "campaign.paused"[]
enabledrequiredboolean
disabledReasonrequiredstring | null: Why Ballast turned it off, when it did
lastDeliveryAtrequiredstring | null
lastStatusrequirednumber | null: HTTP status of the last attempt, 0 when the endpoint didn't answer
deliveredrequirednumber
failedrequirednumber
pendingrequirednumber
createdAtrequiredstring

Send a test event now

POST/api/v1/webhooks/{id}/test

POSTs a signed sample lead.replied event (marked test: true) and returns the endpoint's answer. Not retried.

MCP tool test_webhookOwners and admins

Parameters

idrequiredpath · string

Returns

deliveredrequiredboolean
statusrequirednumber
errorrequiredstring | null
bodyrequiredstring
msrequirednumber