> ## Documentation Index > Fetch the complete documentation index at: https://docs.vocobase.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a webhook endpoint bound to an agent > Same as `POST /config/webhooks`, except the scope is taken from the path. Any `agent_id` in the body is ignored — this route can only bind to the agent in the URL. The secret is returned once and cannot be read again. Labels are unique per **account**, so the same label cannot be reused across agents. ## OpenAPI ````yaml /openapi.json post /agent/{agentId}/webhooks openapi: 3.1.0 info: title: Vocobase API version: '2.0' description: >- API for managing voice AI agents, documents, and calls on the Vocobase platform. servers: - url: https://api.vocobase.com/api/v2 description: Production security: - bearerAuth: [] tags: - name: Config description: >- Read and update account configuration, webhook settings, and telephony credentials. - name: Agents description: Create, read, update, and delete voice AI agents. - name: Voices description: >- List voice tiers, available voices, and stream preview audio for agent configuration. - name: Documents description: Upload, manage, and delete knowledge base documents. - name: Agent Documents description: Link and unlink documents to agents for knowledge base integration. - name: Calls description: Initiate outbound calls and view call history. - name: Phone Numbers description: >- Import DIDs, assign agents for inbound routing, and re-sync carrier Application bindings. - name: Inbound Routing Policies description: >- Define pre-answer routing decisions for inbound calls before AI sessions are created. - name: Telephony Connections description: Create, list, rename, and disconnect named V2 telephony connections. - name: VoiceLink Management description: Manage VoiceLink reseller clients, DID mapping, and readiness sync. - name: Projects description: Organize agents into projects. Every agent belongs to exactly one project. - name: Dictionaries description: Speech-recognition dictionary CRUD and agent attachment. - name: Sessions description: Browser-initiated WebRTC voice sessions for in-app voice agents. - name: Campaigns description: Batch outbound calling. - name: Billing description: Balance, transactions, and usage summaries. - name: Custom Functions description: HTTP endpoints the agent can call mid-conversation. - name: Extraction Sets description: Reusable sets of post-call extraction fields. - name: Lifecycle Hooks description: Automatic pre-call and post-call integration steps. - name: Messaging description: Bring-your-own WhatsApp sending. - name: Integration Logs description: Audit trail for integration calls. - name: Connectors description: Catalog of tools an agent can be connected to. - name: Customers description: B2B2B sub-tenants and their tool connections. - name: Agent Tools description: Binding connectors and connections to an agent. paths: /agent/{agentId}/webhooks: post: tags: - Config summary: Create a webhook endpoint bound to an agent description: >- Same as `POST /config/webhooks`, except the scope is taken from the path. Any `agent_id` in the body is ignored — this route can only bind to the agent in the URL. The secret is returned once and cannot be read again. Labels are unique per **account**, so the same label cannot be reused across agents. operationId: createAgentWebhookEndpoint parameters: - name: agentId in: path required: true schema: type: string format: uuid description: Agent ID to bind the endpoint to. requestBody: required: true content: application/json: schema: type: object required: - label - url properties: label: type: string pattern: ^[a-z0-9][a-z0-9-]{0,30}$ description: >- Your chosen endpoint label. Lowercase letters, numbers, and hyphens only; 1-31 characters. Unique per account. example: acme-tenant url: type: string format: uri description: HTTPS URL that receives webhook events. example: https://acme.example.com/vocobase enabled: type: boolean default: true description: Whether the endpoint should receive new webhook events. events: type: array items: $ref: '#/components/schemas/WebhookEventType' default: [] description: >- Event allowlist. Omit or send `[]` to receive every event type. example: label: acme-tenant url: https://acme.example.com/vocobase events: - session.completed responses: '201': description: Webhook endpoint created. Save the secret immediately. content: application/json: schema: type: object properties: success: type: boolean const: true data: allOf: - $ref: '#/components/schemas/WebhookEndpoint' - type: object properties: secret: type: string description: >- HMAC signing secret. Starts with `whsec_`. Returned only once. message: type: string example: success: true data: id: e1f2a3b4-5678-90ab-cdef-1234567890ab label: acme-tenant url: https://acme.example.com/vocobase enabled: true agent_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 agent_name: Acme Sales Bot events: - session.completed last_delivery_at: null last_delivery_status: null created_at: '2026-05-25T10:00:00.000Z' updated_at: '2026-05-25T10:00:00.000Z' secret: whsec_abc123... message: Save this secret — it will not be shown again. '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': description: >- `LABEL_TAKEN` — the label is already used elsewhere on this account — or `LIMIT_EXCEEDED` — this agent already has 5 endpoints. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': $ref: '#/components/responses/InternalError' components: schemas: WebhookEventType: type: string description: >- A webhook event type. This is the complete catalog and the only set accepted in an endpoint's `events` allowlist. `webhook.test` is deliberately absent: it is fired only by `POST /config/webhooks/{id}/test` and always reaches the endpoint being tested regardless of its allowlist. There is no `session.failed` event — a session that ends in a terminal failure is delivered as `session.completed` with `duration_seconds: 0`, `transcript: null`, and a terminal `call.status`. enum: - session.completed - call.status.updated - call.transferred - whatsapp.message.sent - whatsapp.message.failed - whatsapp.message.status_updated WebhookEndpoint: type: object properties: id: type: string format: uuid description: Webhook endpoint ID. label: type: string description: Your chosen endpoint label. Unique per account, not per scope. url: type: string format: uri description: HTTPS endpoint URL. enabled: type: boolean description: Whether this endpoint receives new webhook events. agent_id: type: - string - 'null' format: uuid description: >- Scope. `null` means account-wide — the endpoint receives events for every agent on the account. A non-null value binds the endpoint to that one agent. Set once at creation and immutable afterwards. agent_name: type: - string - 'null' description: >- Display name of the scoped agent. `null` for an account-wide endpoint. events: type: array items: $ref: '#/components/schemas/WebhookEventType' description: >- Event allowlist. An empty array means every event type, including ones added to the platform later. last_delivery_at: type: - string - 'null' format: date-time last_delivery_status: type: - integer - 'null' created_at: type: string format: date-time updated_at: type: string format: date-time ErrorResponse: type: object properties: success: type: boolean const: false error: type: object properties: code: type: string message: type: string required: - code - message required: - success - error responses: ValidationError: description: Validation error in request body or parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: VALIDATION_ERROR message: agent_name is required and must be max 50 characters Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing API key NotFound: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: Resource not found InternalError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_ERROR message: An unexpected error occurred securitySchemes: bearerAuth: type: http scheme: bearer description: >- API key in format: `rg_live_xxxx`. Pass as a Bearer token in the Authorization header. ````