> ## Documentation Index > Fetch the complete documentation index at: https://docs.kejue.co/llms.txt > Use this file to discover all available pages before exploring further. # Create Webhook > Create a webhook subscription. Events will be POSTed to the URL with HMAC-SHA256 signature verification. ## OpenAPI ````yaml /openapi.json post /webhooks openapi: 3.1.0 info: title: Kejue Public API description: >- The Kejue Public API lets you programmatically create calls, manage campaigns, and retrieve call results. ## Authentication All requests require an API key passed in the `X-API-Key` header: ``` X-API-Key: kej_live_... ``` API keys are scoped to a workspace. Create and manage keys from the Kejue dashboard under **Settings → API Keys**. ## Base URL ``` https://api.kejue.co/api/v1 ``` ## Rate Limits API requests are rate-limited per workspace. If you exceed the limit you'll receive a `429 Too Many Requests` response. ## Errors All error responses follow a consistent format: ```json { "error": "Human-readable message", "code": "ERROR_CODE", "details": {} } ``` version: 1.0.0 servers: - url: https://api.kejue.co/api/v1 description: Production security: - ApiKeyAuth: [] tags: - name: Agents description: >- Create and manage AI agents (personas). Each agent has a name, prompt, voice configuration, and optional tools. Agents are the core building block — attach voice configs, tools, and use them to make calls. - name: Calls description: >- Create outbound calls, retrieve call details and transcripts, and list calls with filtering. Each call is associated with a contact and optionally an agent and campaign. - name: Persona Calls description: >- Create calls with the full agent configuration pre-loaded. Applies the complete settings hierarchy (workspace → agent → campaign → overrides) with all agent tools, tags, scoring, and webhooks inherited automatically. - name: Contacts description: >- Create and manage contacts. Contacts represent the people your agents call. Each contact has a phone number, name, and optional metadata. Supports single creation, bulk import, and CSV upload. - name: Campaigns description: >- Create and manage calling campaigns. Campaigns let you batch-call a list of contacts with shared settings, scheduling, and retry logic. - name: Tools description: >- Create and manage custom HTTP tools that agents can invoke during calls. Tools let agents fetch data, trigger actions, or integrate with external systems mid-conversation. Each tool supports three parameter types: - **Dynamic parameters** — filled by the AI at runtime (visible to the AI) - **Static parameters** — fixed values sent with every invocation (hidden from the AI) - **System parameters** — values injected from the execution context at runtime, such as `call_id`, `contact_id`, or `workspace_id` (hidden from the AI) - name: Voices description: List available voices for use in agent voice configurations. - name: Phone Numbers description: List phone numbers available in your workspace for making outbound calls. - name: Webhooks description: >- Create and manage webhook subscriptions. Receive real-time notifications for call events (started, ended, etc.) at your specified URL. - name: Models description: List available AI models for use in agent voice configurations. paths: /webhooks: post: tags: - Webhooks summary: Create Webhook description: >- Create a webhook subscription. Events will be POSTed to the URL with HMAC-SHA256 signature verification. operationId: create_webhook_webhooks_post parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWebhook' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/WebhookResponse' '400': description: >- One of the requested event types is invalid, persona_id is missing for a persona-scoped webhook, or signing_method requires a secret. content: application/json: example: error: 'Invalid event type: foo.bar' code: BAD_REQUEST details: {} schema: $ref: '#/components/schemas/ErrorResponse' '401': description: >- Missing or invalid API key. Pass a workspace API key in the `X-API-Key` header. content: application/json: example: error: Invalid or missing API key code: UNAUTHORIZED details: {} schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Request body or query parameters failed validation. content: application/json: example: error: Validation failed code: VALIDATION_ERROR details: errors: - field: body.name message: Field required type: missing schema: $ref: '#/components/schemas/ErrorResponse' security: - ApiKeyAuth: [] components: schemas: CreateWebhook: properties: name: anyOf: - type: string - type: 'null' title: Name description: Display name for the webhook url: type: string maxLength: 2083 minLength: 1 format: uri title: Url description: URL to send webhook events to events: items: type: string type: array title: Events description: List of event types to subscribe to. Use '*' for all events. examples: - - call.ended - contact.updated - - '*' signing_method: $ref: '#/components/schemas/SigningMethod' description: 'Signing method: hmac_sha256, hmac_sha1, bearer, basic_auth, none' default: hmac_sha256 secret: anyOf: - type: string - type: 'null' title: Secret description: Signing secret (auto-creates workspace secret) scope_type: $ref: '#/components/schemas/WebhookScopeType' description: >- Scope filtering: 'global' for all events, 'persona' for specific persona default: global persona_id: anyOf: - type: string - type: 'null' title: Persona Id description: Persona ID if scope_type is 'persona' timeout_ms: type: integer maximum: 30000 minimum: 1000 title: Timeout Ms description: Request timeout in milliseconds (1000-30000) default: 5000 max_retries: type: integer maximum: 10 minimum: 0 title: Max Retries description: Maximum retry attempts (0-10) default: 3 type: object required: - url - events title: CreateWebhook description: Create a webhook subscription (public API). WebhookResponse: properties: id: type: string title: Id name: anyOf: - type: string - type: 'null' title: Name url: type: string title: Url events: items: type: string type: array title: Events signing_method: $ref: '#/components/schemas/SigningMethod' scope_type: $ref: '#/components/schemas/WebhookScopeType' persona_id: anyOf: - type: string - type: 'null' title: Persona Id delivery_settings: $ref: '#/components/schemas/WebhookDeliverySettings' stats: $ref: '#/components/schemas/WebhookStats' last_delivery_at: anyOf: - type: string - type: 'null' title: Last Delivery At last_error: anyOf: - type: string - type: 'null' title: Last Error created_at: anyOf: - type: string - type: 'null' title: Created At updated_at: anyOf: - type: string - type: 'null' title: Updated At type: object required: - id - url - events - signing_method - scope_type - delivery_settings - stats title: WebhookResponse description: Webhook subscription response (public-safe). ErrorResponse: properties: error: type: string title: Error code: type: string title: Code details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details type: object required: - error - code title: ErrorResponse description: Standard error response. example: code: NOT_FOUND details: contact_id: '123' error: Contact not found SigningMethod: type: string enum: - hmac_sha256 - hmac_sha1 - bearer - basic_auth - none title: SigningMethod description: Webhook signing methods. WebhookScopeType: type: string enum: - global - persona title: WebhookScopeType description: Webhook scope types. WebhookDeliverySettings: properties: timeout_ms: type: integer title: Timeout Ms max_retries: type: integer title: Max Retries backoff_ms: type: integer title: Backoff Ms type: object required: - timeout_ms - max_retries - backoff_ms title: WebhookDeliverySettings description: Delivery configuration for a webhook subscription. WebhookStats: properties: total_deliveries: type: integer title: Total Deliveries failed_deliveries: type: integer title: Failed Deliveries success_rate: type: number title: Success Rate type: object required: - total_deliveries - failed_deliveries - success_rate title: WebhookStats description: Delivery statistics for a webhook subscription. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: Workspace API key (e.g. `kej_live_...`) ````