AgentLine Webhooks API

openapi: 3.2.0
info:
  title: Agentline Cloud Webhooks API
  version: 0.3.0
  x-refined-note:
  - x-guidance differs across the merged source definitions and was not carried
  description: 'Operations tagged Webhooks across 2 of this provider''s published API definitions: agentline.cloud_openapi.json, agentline-cloud-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.agentline.cloud
  description: Production
tags:
- name: Webhooks
paths:
  /v1/webhooks:
    get:
      tags:
      - Webhooks
      summary: Get Webhooks
      description: 'List the account''s per-agent webhook configuration(s).


        Secrets are **masked**. Pass `agent_id` to inspect a single agent''s webhook.

        The full secret is only ever shown once, on the POST that creates/replaces it.'
      operationId: get_webhook
      security:
      - API Key or OAuth: []
      parameters:
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Inspect one agent's webhook (omit to list all)
          title: Agent Id
        description: Inspect one agent's webhook (omit to list all)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-fern-sdk-group-name:
      - webhooks
      x-fern-sdk-method-name: list
    post:
      tags:
      - Webhooks
      summary: Set Webhook
      description: 'Create or replace an agent''s webhook.


        The configured URL receives ALL of that agent''s event types — `call.received` (inbound answer), `call.utterance`, `call.completed`, `call.owner_task`, `call.failed`, `call.busy`, `call.no-answer`, `call.canceled`, `sms.received`, and `webhook.test` — as signed JSON POSTs. Each agent may have at most one

        webhook; POSTing again replaces it.


        - `agent_id`: the agent whose events this webhook receives (required).

        - `secret`: HMAC signing secret. Omit to auto-generate.


        The response returns the full `secret` **once** — store it to verify the

        signature header on deliveries.'
      operationId: set_webhook
      security:
      - API Key or OAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookConfig'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookCreated'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-fern-sdk-group-name:
      - webhooks
      x-fern-sdk-method-name: set
    delete:
      tags:
      - Webhooks
      summary: Delete Webhook
      description: 'Remove an agent''s webhook. No events for that agent will be delivered via

        HTTP afterwards; they remain available via GET /v1/events (the mailbox).'
      operationId: delete_webhook
      security:
      - API Key or OAuth: []
      parameters:
      - name: agent_id
        in: query
        required: true
        schema:
          type: string
          description: Agent whose webhook to delete
          title: Agent Id
        description: Agent whose webhook to delete
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-fern-sdk-group-name:
      - webhooks
      x-fern-sdk-method-name: delete
    servers:
    - url: https://api.agentline.cloud
      description: Production
  /v1/webhooks/test:
    post:
      tags:
      - Webhooks
      summary: Test Webhook
      description: 'Fire a signed `webhook.test` event to the agent''s webhook.


        Uses the exact same event bus (publish_event) that real telephony events use,

        so a successful delivery confirms the entire pipeline is wired correctly.

        Returns 404 if no webhook is configured for the agent.'
      operationId: test_webhook
      security:
      - API Key or OAuth: []
      parameters:
      - name: agent_id
        in: query
        required: true
        schema:
          type: string
          description: Agent whose webhook to test
          title: Agent Id
        description: Agent whose webhook to test
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-fern-sdk-group-name:
      - webhooks
      x-fern-sdk-method-name: test
    servers:
    - url: https://api.agentline.cloud
      description: Production
  /v1/webhooks/account:
    get:
      tags:
      - Webhooks
      summary: Get Account Webhook
      operationId: get_account_notification_webhook
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - API Key or OAuth: []
    post:
      tags:
      - Webhooks
      summary: Set Account Webhook
      description: 'One signed notification URL for all agents. No call.utterance or relay.


        Only pilot accounts can use this endpoint. Omitted signing settings are

        preserved on update; the full secret is returned on this write only.

        Existing per-agent webhook relay is suppressed while this is configured.'
      operationId: set_account_notification_webhook
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountWebhookConfig'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - API Key or OAuth: []
    delete:
      tags:
      - Webhooks
      summary: Delete Account Webhook
      operationId: delete_account_notification_webhook
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - API Key or OAuth: []
    servers:
    - url: https://api.agentline.cloud
  /v1/webhooks/account/test:
    post:
      tags:
      - Webhooks
      summary: Test Account Webhook
      operationId: test_account_notification_webhook
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - API Key or OAuth: []
    servers:
    - url: https://api.agentline.cloud
  /v1/webhooks/account/deliveries:
    get:
      tags:
      - Webhooks
      summary: Delivery Status
      operationId: account_notification_delivery_status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - API Key or OAuth: []
    servers:
    - url: https://api.agentline.cloud
  /v1/webhooks/api-key:
    get:
      tags:
      - Webhooks
      summary: Get Key Webhook
      operationId: get_api_key_notification_webhook
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - API Key or OAuth: []
    post:
      tags:
      - Webhooks
      summary: Set Key Webhook
      description: 'Register one notify-only URL for the API key authenticating this request.


        Only ooctoo@monid.ai is eligible. The URL receives call/SMS events for

        numbers provisioned or explicitly assigned to this key. It takes precedence

        over the account-wide URL for those numbers. Save the returned signing secret.'
      operationId: set_api_key_notification_webhook
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyWebhookConfig'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - API Key or OAuth: []
    delete:
      tags:
      - Webhooks
      summary: Delete Key Webhook
      operationId: delete_api_key_notification_webhook
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - API Key or OAuth: []
    servers:
    - url: https://api.agentline.cloud
  /v1/webhooks/api-key/numbers:
    get:
      tags:
      - Webhooks
      summary: Key Numbers
      operationId: list_api_key_notification_numbers
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - API Key or OAuth: []
    servers:
    - url: https://api.agentline.cloud
  /v1/webhooks/api-key/numbers/{number_id}:
    put:
      tags:
      - Webhooks
      summary: Assign Number Key
      description: Assign an older, untracked number to this key. A different key cannot take it.
      operationId: assign_legacy_number_to_api_key
      security:
      - API Key or OAuth: []
      parameters:
      - name: number_id
        in: path
        required: true
        schema:
          type: string
          title: Number Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://api.agentline.cloud
  /v1/webhooks/api-key/test:
    post:
      tags:
      - Webhooks
      summary: Test Key Webhook
      operationId: test_api_key_notification_webhook
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - API Key or OAuth: []
    servers:
    - url: https://api.agentline.cloud
  /v1/webhooks/api-key/deliveries:
    get:
      tags:
      - Webhooks
      summary: Key Delivery Status
      operationId: api_key_notification_delivery_status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - API Key or OAuth: []
    servers:
    - url: https://api.agentline.cloud
components:
  schemas:
    WebhookCreated:
      properties:
        agent_id:
          type: string
          title: Agent Id
          description: Agent this webhook is scoped to
        url:
          type: string
          title: Url
          description: Configured webhook URL
        secret:
          type: string
          title: Secret
          description: Full signing secret. Save it now — it is masked on subsequent reads.
        signature_header:
          type: string
          title: Signature Header
          description: Header name used for HMAC-SHA256 signature delivery.
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
          description: When the webhook was last (re)configured
      type: object
      required:
      - agent_id
      - url
      - secret
      - signature_header
      title: WebhookCreated
      description: Returned on POST — exposes the full secret this one time.
    WebhookConfig:
      properties:
        url:
          type: string
          maxLength: 2083
          minLength: 1
          format: uri
          title: Url
          description: HTTPS URL that will receive this agent's events as signed JSON POSTs. Setting this replaces any existing webhook for the agent.
        agent_id:
          type: string
          title: Agent Id
          description: ID of the agent whose events this webhook receives. Each agent may have at most one webhook.
        secret:
          anyOf:
          - type: string
          - type: 'null'
          title: Secret
          description: Optional HMAC signing secret. Auto-generated if omitted. Used to verify the signature header on delivered payloads.
        signature_header:
          anyOf:
          - type: string
          - type: 'null'
          title: Signature Header
          description: Header name for the HMAC-SHA256 signature of the raw body. Defaults to 'X-Webhook-Signature' (natively verified by Hermes, OpenClaw, and other agent platforms). Set to 'X-Hub-Signature-256' for GitHub-style verification, or any custom header name your platform expects. Omit to keep the existing value when updating.
      type: object
      required:
      - url
      - agent_id
      title: WebhookConfig
      description: Body for POST /v1/webhooks (create or replace an agent's webhook).
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    WebhookCreated_2:
      properties:
        agent_id:
          type: string
          title: Agent Id
          description: Agent this webhook is scoped to
        url:
          type: string
          title: Url
          description: Configured webhook URL
        secret:
          type: string
          title: Secret
          description: Full signing secret. Save it now — it is masked on subsequent reads.
        signature_header:
          type: string
          title: Signature Header
          description: Header name used for HMAC-SHA256 signature delivery.
        protocol:
          type: string
          title: Protocol
          description: Live relay protocol.
          default: agentline-relay/1
        capabilities:
          additionalProperties: true
          type: object
          title: Capabilities
          description: Declared relay v2 capabilities.
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
          description: When the webhook was last (re)configured
      type: object
      required:
      - agent_id
      - url
      - secret
      - signature_header
      title: WebhookCreated
      description: Returned on POST — exposes the full secret this one time.
    AccountWebhookConfig:
      properties:
        url:
          type: string
          maxLength: 2083
          minLength: 1
          format: uri
          title: Url
        secret:
          anyOf:
          - type: string
          - type: 'null'
          title: Secret
        signature_header:
          anyOf:
          - type: string
          - type: 'null'
          title: Signature Header
      type: object
      required:
      - url
      title: AccountWebhookConfig
    ApiKeyWebhookConfig:
      properties:
        url:
          type: string
          maxLength: 2083
          minLength: 1
          format: uri
          title: Url
        secret:
          anyOf:
          - type: string
          - type: 'null'
          title: Secret
        signature_header:
          anyOf:
          - type: string
          - type: 'null'
          title: Signature Header
      additionalProperties: false
      type: object
      required:
      - url
      title: ApiKeyWebhookConfig
    WebhookCapabilities:
      properties:
        supports_amend:
          type: boolean
          title: Supports Amend
          description: 'Accepts call.task.amend POSTs: caller follow-ups on the open task, same turn_id, higher revision. When false, AgentLine holds follow-ups and sends them as one merged task after the current one settles.'
          default: false
        supports_cancel:
          type: boolean
          title: Supports Cancel
          description: Accepts call.task.cancel POSTs when the caller withdraws a task.
          default: false
        briefing:
          type: boolean
          title: Briefing
          description: Accepts call.session.start at call start and pushes facts the caller is likely to need (disposition=facts, no turn_id).
          default: true
        streams_progress:
          type: boolean
          title: Streams Progress
          description: Pushes partial/progress updates while it works.
          default: false
      type: object
      title: WebhookCapabilities
      description: What a webhook runtime supports on live relay calls (protocol v2).
    WebhookConfig_2:
      properties:
        url:
          type: string
          maxLength: 2083
          minLength: 1
          format: uri
          title: Url
          description: HTTPS URL that will receive this agent's events as signed JSON POSTs. Setting this replaces any existing webhook for the agent.
        agent_id:
          type: string
          title: Agent Id
          description: ID (agt_...) of the agent whose events this webhook receives, from create_agent or list_agents. Each agent may have at most one webhook.
        secret:
          anyOf:
          - type: string
          - type: 'null'
          title: Secret
          description: Optional HMAC signing secret used to verify the signature header on delivered payloads. Omit to keep the current secret, or to auto-generate one for a new webhook.
        signature_header:
          anyOf:
          - type: string
          - type: 'null'
          title: Signature Header
          description: Header name for the HMAC-SHA256 signature of the raw body. Defaults to 'X-Webhook-Signature' (natively verified by Hermes, OpenClaw, and other agent platforms). Set to 'X-Hub-Signature-256' for GitHub-style verification, or any custom header name your platform expects. Omit to keep the existing value when updating.
        protocol:
          anyOf:
          - type: string
            enum:
            - agentline-relay/1
            - agentline-relay/2
          - type: 'null'
          title: Protocol
          description: 'Live relay protocol. ''agentline-relay/1'' (default): one call.utterance POST per task, answer in the response body or via push. ''agentline-relay/2'': typed POSTs (call.session.start, call.task.open, call.task.amend, call.task.cancel, call.session.end); answer only via POST /v1/calls/{call_id}/context and return 202 quickly. Omit to keep the existing value when updating.'
        capabilities:
          anyOf:
          - $ref: '#/components/schemas/WebhookCapabilities'
          - type: 'null'
          description: Relay v2 capabilities. Omit to keep the existing value when updating.
      type: object
      required:
      - url
      - agent_id
      title: WebhookConfig
  securitySchemes:
    API_Key_or_OAuth:
      type: http
      description: 'AgentLine API key. Get one via the email OTP flow (POST /v1/auth/otp then POST /v1/auth/verify). Pass as: Authorization: Bearer al_live_... (legacy sk_live_... still works).'
      scheme: bearer
      bearerFormat: API key (al_live_...)
      x-fern-bearer:
        name: apiKey
        env: AGENTLINE_API_KEY
x-refined-from:
- agentline.cloud_openapi.json
- agentline-cloud-openapi.json