> ## Documentation Index > Fetch the complete documentation index at: https://docs.samora.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create webhook > Creates a new webhook to receive call event notifications. The webhook secret is returned only once during creation and should be saved securely. ## OpenAPI ````yaml POST /v2/webhooks openapi: 3.0.3 info: title: Samora AI API description: > The Samora AI API lets you trigger immediate outbound calls and manage outbound campaigns through the Samora AI system. Use it to start calls with your AI agents, pass per-call context, create campaigns, add recipients, and manage campaign lifecycle from your server. **Authentication:** Every request must include your organization API key in the `X-API-Key` header. These APIs are intended for server-to-server integrations; do not expose your organization API key in browser or mobile clients. **Phone number format:** Destination numbers must be in E.164 format (e.g. `+919876543210`) and include the country code. The pattern is: `+` followed by 10-15 digits. **Call statuses:** When you fetch call details, `status` can be: `PENDING`, `TRIGGERED`, `ONGOING`, `CALL_FINISHED`, `UNANSWERED`, `REJECTED`. **Campaign statuses:** Campaign `status` can be: `DRAFT`, `SCHEDULED`, `IN_PROGRESS`, `PAUSED`, `FINISHED`, `FAILED`, `CANCELLED`. **Campaign lifecycle:** Recipients can be added only while a campaign is `DRAFT` or `PAUSED`. Campaigns can be started only from `DRAFT` or `PAUSED`, stopped only from `IN_PROGRESS`, and cancelled unless they are already `FINISHED`, `FAILED`, or `CANCELLED`. **Campaign API limits:** Request bodies are limited to 2 MiB. Campaign names can be up to 120 characters. List requests support `page_size` up to 100. Add recipients accepts up to 5000 phone numbers per request, and each recipient's `call_variables` can be up to 4 KiB. **Transcripts and recordings:** For finished calls, presigned URLs for transcript and recording are valid for 60 minutes. version: 1.0.0 license: name: Proprietary servers: - url: https://api.samora.ai description: Production server security: - ApiKeyAuth: [] paths: /v2/webhooks: post: description: > Creates a new webhook to receive call event notifications. The webhook secret is returned only once during creation and should be saved securely. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWebhookRequest' examples: basic: value: agent_id: 123e4567-e89b-12d3-a456-426614174000 name: CRM Integration url: https://your-server.com/webhooks/samora events: - CALL_FINISHED - CALL_FAILED withOptions: value: agent_id: 123e4567-e89b-12d3-a456-426614174000 name: Full Data Webhook url: https://your-server.com/webhooks/samora events: - CALL_FINISHED data_options: include_transcript: true include_recording_url: true custom_headers: X-Custom-Header: my-value responses: '201': description: Webhook created successfully content: application/json: schema: type: object required: - message - data properties: message: type: string data: $ref: '#/components/schemas/WebhookResponse' additionalProperties: false examples: created: value: message: >- Webhook created successfully. Save the secret - it will not be shown again. data: id: 550e8400-e29b-41d4-a716-446655440000 agent_id: 123e4567-e89b-12d3-a456-426614174000 name: CRM Integration url: https://your-server.com/webhooks/samora secret: whsec_abc123def456ghi789... events: - CALL_FINISHED - CALL_FAILED data_options: include_transcript: false include_recording_url: false custom_headers: {} is_active: true created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' '400': description: Invalid request body content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidRequest: value: message: Invalid request body '403': description: Agent does not belong to your company content: application/json: schema: $ref: '#/components/schemas/Error' examples: forbidden: value: message: Agent does not belong to your company components: schemas: CreateWebhookRequest: type: object required: - agent_id - name - url - events properties: agent_id: type: string format: uuid description: The UUID of the agent this webhook is associated with. name: type: string minLength: 1 maxLength: 255 description: A friendly name for this webhook. url: type: string format: uri description: The HTTPS URL where webhook payloads will be sent. events: type: array minItems: 1 description: List of event types to subscribe to. items: type: string enum: - CALL_STARTED - CALL_FINISHED - CALL_FAILED data_options: $ref: '#/components/schemas/DataOptions' custom_headers: $ref: '#/components/schemas/CustomHeaders' additionalProperties: false WebhookResponse: type: object properties: id: type: string format: uuid description: Unique identifier for the webhook. agent_id: type: string format: uuid description: The agent this webhook is associated with. name: type: string description: The webhook name. url: type: string format: uri description: The webhook URL. secret: type: string description: The webhook signing secret. Returned only on creation. events: type: array items: type: string description: Subscribed event types. data_options: $ref: '#/components/schemas/DataOptions' custom_headers: $ref: '#/components/schemas/CustomHeaders' is_active: type: boolean description: Whether the webhook is active. created_at: type: string format: date-time updated_at: type: string format: date-time additionalProperties: false Error: type: object required: - message properties: message: type: string description: Error message. additionalProperties: false DataOptions: type: object properties: include_transcript: type: boolean default: false description: Include the full call transcript in webhook payload. include_recording_url: type: boolean default: false description: Include the call recording URL in webhook payload. additionalProperties: false CustomHeaders: type: object description: Custom HTTP headers to send with webhook requests. additionalProperties: type: string securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: Your unique organization API key. Required on all requests. ````