API reference · Webhooks

Create a subscription

POSThttps://goblins-call-api.onrender.com/v1/webhooks

Registers a URL that receives events from every call in your workspace. This is the only response that carries the signing secret in full.

Needs a workspace API key.

Body

urlstringRequired

Where events are delivered, as a POST with a JSON body. Must be a public address.

eventsstring[]Requiredat least 1

The event types to receive, or ["*"] for all of them.

descriptionstringOptionalup to 200 chars

A label for your own reference.

enabledbooleanOptionaldefault true

false keeps the subscription without delivering to it.

secretstringOptionalat least 16 chars

Your own signing secret. One is generated when this is left out.

Errors

400

The body failed validation. details lists each field and what is wrong with it.

400URL_NOT_ALLOWED

The URL is not a public http(s) address.

Every request can also answer 401, 429 and 500: see Errors.

Notes

Store the secret before moving on; later reads return it masked.
For one agent’s calls only, set webhookUrl on the agent. For one call only, send webhooks when starting it.

curl -X POST "https://goblins-call-api.onrender.com/v1/webhooks" \
  -H "Authorization: Bearer $CRACKLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://your-app.com/webhooks/crackle",
  "events": [
    "call.ended"
  ]
}'

Response · 201 Created

{
  "webhook": {
    "id": "wh_3f9a1c2b7d4e5f60",
    "userId": "usr_8c1d2e3f4a5b",
    "url": "https://your-app.com/webhooks/crackle",
    "events": ["call.ended"],
    "enabled": true,
    "secret": "whsec_9c4f1e7a2b6d8035f1a9c2e4b7d60813a5f2c9e1b4d7a630",
    "createdAt": "2026-10-11T08:31:10.000Z",
    "updatedAt": "2026-10-11T08:31:10.000Z"
  }
}