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

# Register a webhook

> Creates a webhook destination for direct call and SMS conversation events. The signing secret is returned only once in the create response. Store the secret and use it to verify every future delivery. This configuration backs the default destination used by agent-service webhook delivery.



## OpenAPI

````yaml /openapi/v1.json post /webhooks
openapi: 3.0.3
info:
  title: PAM Outbound API
  version: 1.0.0
  description: >-
    External API for creating outbound calls, starting SMS conversations,
    managing API keys, and receiving webhook events.
servers:
  - url: https://api.pamhq.com/v1
    description: Production
security:
  - bearerApiKey: []
tags:
  - name: Calls
    description: Start and manage outbound voice calls.
  - name: SMS Conversations
    description: Start and manage outbound SMS conversations.
  - name: API Keys
    description: Create, list, inspect, and revoke API keys.
  - name: Webhooks
    description: Configure direct call and SMS conversation webhook destinations.
  - name: Webhook Events
    description: Canonical webhook payloads emitted by calls and SMS conversations.
paths:
  /webhooks:
    post:
      tags:
        - Webhooks
      summary: Register a webhook
      description: >-
        Creates a webhook destination for direct call and SMS conversation
        events. The signing secret is returned only once in the create response.
        Store the secret and use it to verify every future delivery. This
        configuration backs the default destination used by agent-service
        webhook delivery.
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '201':
          description: Webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookCreatedResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    CreateWebhookRequest:
      type: object
      required:
        - url
        - events
      properties:
        url:
          type: string
          format: uri
          description: HTTPS endpoint that receives webhook POST requests.
        events:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/WebhookEvent'
    WebhookCreatedResponse:
      allOf:
        - $ref: '#/components/schemas/ResponseEnvelope'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/WebhookCreated'
    WebhookEvent:
      type: string
      enum:
        - call.started
        - call.ended
        - call.analyzed
        - call.failed
        - sms.message_sent
        - sms.message_received
        - sms.message_delivery_updated
        - sms.tool_call_invocation
        - sms.tool_call_result
    ResponseEnvelope:
      type: object
      properties:
        data: {}
        meta:
          $ref: '#/components/schemas/Meta'
    WebhookCreated:
      allOf:
        - $ref: '#/components/schemas/Webhook'
        - type: object
          properties:
            secret:
              type: string
              description: Webhook signing secret. Returned only once.
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              description: Optional field-level validation details.
              nullable: true
        meta:
          $ref: '#/components/schemas/Meta'
    Meta:
      type: object
      properties:
        requestId:
          type: string
    Webhook:
      type: object
      properties:
        id:
          type: string
          format: uuid
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEvent'
        isActive:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
  responses:
    ValidationError:
      description: Request validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing, expired, revoked, or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerApiKey:
      type: http
      scheme: bearer
      description: 'API key provided as `Authorization: Bearer <key>`.'
      x-default: pk_live_your_api_key

````