> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumisreach.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a call webhook

> Registers an HTTPS URL that LumisReach POSTs to when a call on one of your numbers (or only `phone_number_id`, if given) starts (`call.started`) and when it ends (`call.ended`). `call.ended` is sent once the call's transcript is saved and carries the full transcript, as plain text and turn by turn. Covers inbound and outbound AI calls on both voice stacks. Each delivery is signed with `X-LumisReach-Signature-256` (hex HMAC-SHA256 of the raw body, keyed with the `secret` returned here once). A delivery that fails or gets a non-2xx response is retried 3 times over about 36 minutes.



## OpenAPI

````yaml /openapi.json post /v1/voice/calls/webhooks
openapi: 3.1.0
info:
  title: LumisReach v1 API
  version: 1.0.0
  description: >-
    Programmatic access to the LumisReach voice platform — calls, numbers,
    caller trust, and brands.
  contact:
    name: LumisReach
    email: founders@lumisreach.com
servers:
  - url: https://api.lumisreach.com/api
security:
  - bearerAuth: []
tags:
  - name: Phone Numbers
  - name: Caller IDs
  - name: Enterprise Registration
  - name: Branded Calling
  - name: Calls
  - name: SMS
  - name: WebRTC
  - name: Reputation
  - name: Usage
  - name: Account
  - name: Conversation History
  - name: Documents
  - name: Quick Agent Actions
  - name: Sub-entities
paths:
  /v1/voice/calls/webhooks:
    post:
      tags:
        - Calls
      summary: Create a call webhook
      description: >-
        Registers an HTTPS URL that LumisReach POSTs to when a call on one of
        your numbers (or only `phone_number_id`, if given) starts
        (`call.started`) and when it ends (`call.ended`). `call.ended` is sent
        once the call's transcript is saved and carries the full transcript, as
        plain text and turn by turn. Covers inbound and outbound AI calls on
        both voice stacks. Each delivery is signed with
        `X-LumisReach-Signature-256` (hex HMAC-SHA256 of the raw body, keyed
        with the `secret` returned here once). A delivery that fails or gets a
        non-2xx response is retried 3 times over about 36 minutes.
      operationId: v1_voice_calls_webhooks_post
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            UUID — when present, deduplicates repeat submissions. See
            /api-reference/idempotency.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                url:
                  type: string
                  maxLength: 2048
                  format: uri
                  description: HTTPS endpoint that receives a POST for every call event
                events:
                  description: >-
                    Which events to send. Defaults to both `call.started` and
                    `call.ended`.
                  minItems: 1
                  type: array
                  items:
                    type: string
                    enum:
                      - call.started
                      - call.ended
                phone_number_id:
                  description: >-
                    Only calls on this number (id from `GET /v1/phone-numbers`).
                    Omit for all your numbers.
                  type: integer
                  minimum: -9007199254740991
                  maximum: 9007199254740991
                description:
                  description: A label for the webhook
                  type: string
                  maxLength: 100
              required:
                - url
              additionalProperties: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $schema: http://json-schema.org/draft-07/schema#
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      url:
                        type: string
                      description:
                        anyOf:
                          - type: string
                          - type: 'null'
                      active:
                        type: boolean
                      phone_number_id:
                        anyOf:
                          - type: number
                          - type: 'null'
                      phone_number:
                        anyOf:
                          - type: string
                          - type: 'null'
                      events:
                        type: array
                        items:
                          type: string
                          enum:
                            - call.started
                            - call.ended
                      created_at:
                        type: string
                      secret:
                        type: string
                        description: >-
                          Signing secret. Every delivery carries
                          `X-LumisReach-Signature-256`: the hex HMAC-SHA256 of
                          the raw body with this secret. Shown once.
                    required:
                      - id
                      - url
                      - description
                      - active
                      - phone_number_id
                      - phone_number
                      - events
                      - created_at
                      - secret
                    additionalProperties: false
                required:
                  - data
                additionalProperties: false
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Conflict (incl. idempotency conflicts)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
components:
  schemas:
    ErrorEnvelope:
      type: object
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            fields:
              type: object
              additionalProperties:
                type: string
            doc_url:
              type: string
              format: uri
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````