Webhooks

Webhooks let you subscribe to project events and receive an HTTP POST to your URL when the event occurs. All endpoints require the api-key header and are free.

Available events

Event	Fired when
`agent.prompt.finished`	The AI agent finishes processing a prompt
`project.credit_limit.reached`	A project reaches its credit limit

Webhook payload delivered to your URL:

json

{
  "event": "agent.prompt.finished",
  "timestamp": "2026-03-17T10:30:00.000Z",
  "data": {
    "projectId": "my-app",
    "status": "done",
    "prompt": "Build a SaaS landing page..."
  }
}

#Register Webhook

PUT/api/v1/vcaas/webhooksFree

Subscribe to an event. You'll receive a POST to your URL when the event occurs.

Body parameters

Field	Type	Required	Description
`url`	string	Yes	HTTPS URL to receive webhook POST
`event`	string	Yes	Event type to subscribe to. See available events above
`headers`	object	No	Custom headers to include in webhook POST

Response fields

Field	Type	Description
`data.id`	string	Webhook ID
`data.url`	string	The registered URL
`data.headers`	object	Custom headers
`data.event`	string	The subscribed event
`data.createdAt`	string	ISO 8601 date

Example request

bash

curl -X PUT \
  -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://yourserver.com/webhook","event":"agent.prompt.finished"}' \
  https://api-accounts.totalum.app/api/v1/vcaas/webhooks

Success · 200 OK

json

{
  "errors": null,
  "data": {
    "id": "65f1a2b3c4d5e6f7a8b9c0d1",
    "url": "https://yourserver.com/webhook",
    "event": "agent.prompt.finished",
    "createdAt": "2026-03-17T10:00:00.000Z"
  }
}

Error · 400

json

{
  "errors": {
    "errorCode": "MISSING_WEBHOOK_FIELDS",
    "errorMessage": "url and event are required"
  },
  "data": null
}

Error codes

Code	HTTP	Meaning
`MISSING_WEBHOOK_FIELDS`	400	url and event are required
`INVALID_WEBHOOK_URL`	400	Webhook URL must use HTTPS
`INVALID_WEBHOOK_EVENT`	400	Event not in allowed list
`WEBHOOK_EVENT_ALREADY_EXISTS`	409	A webhook for this event already exists

#List Webhooks

GET/api/v1/vcaas/webhooksFree

Get all your registered webhooks.

Response fields

Field	Type	Description
`data.webhooks`	array	Array of webhooks
`data.webhooks[].id`	string	Webhook ID
`data.webhooks[].url`	string	Destination URL
`data.webhooks[].headers`	object	Custom headers
`data.webhooks[].event`	string	Subscribed event
`data.webhooks[].createdAt`	string	ISO 8601 date

Example request

bash

curl -H "api-key: tlm_sk_your_key" \
  https://api-accounts.totalum.app/api/v1/vcaas/webhooks

Success · 200 OK

json

{
  "errors": null,
  "data": {
    "webhooks": [
      {
        "id": "65f1a2b3c4d5e6f7a8b9c0d1",
        "url": "https://yourserver.com/webhook",
        "event": "agent.prompt.finished",
        "createdAt": "2026-03-17T10:00:00.000Z"
      }
    ]
  }
}

#Delete Webhook

DELETE/api/v1/vcaas/webhooks/:webhookIdFree

Remove a webhook subscription.

Path parameters

Parameter	Type	Description
`webhookId`	string	The webhook ID

Response fields

Field	Type	Description
`data.success`	boolean	true on success

Example request

bash

curl -X DELETE -H "api-key: tlm_sk_your_key" \
  https://api-accounts.totalum.app/api/v1/vcaas/webhooks/65f1a2b3c4d5e6f7a8b9c0d1

Success · 200 OK

json

{ "errors": null, "data": { "success": true } }

Error · 404

json

{
  "errors": {
    "errorCode": "WEBHOOK_NOT_FOUND",
    "errorMessage": "Webhook not found"
  },
  "data": null
}

Error codes

Code	HTTP	Meaning
`WEBHOOK_NOT_FOUND`	404	Webhook not found