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

# Test webhook endpoint

> Tests a webhook endpoint with realistic payload simulation. Sends a test payload to the webhook URL
and validates the response. Returns test results including HTTP status, response data, and execution time.

## Webhook Types

**Start Webhook**:

* Called when a call begins
* Can modify agent configuration dynamically
* Returns start webhook response with optional config overrides

**Tool Webhook**:

* Called when agent uses a custom tool
* Requires tool name and arguments
* Returns tool execution results

**Transfer Webhook**:

* Called before transferring a call
* Returns transfer destination information

**Result Webhooks** (Completed, Failed, Deadline):

* Fire-and-forget notifications
* No response data expected

## Test Response

The test returns:

* **Success**: Whether the webhook responded successfully
* **HTTP status**: Status code from webhook endpoint
* **Response data**: Parsed response from webhook
* **Validation result**: Schema validation for start webhooks
* **Time taken**: Execution time in milliseconds
* **Error**: Error message if test failed


## OpenAPI

````yaml https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/webhooks/test
openapi: 3.0.4
info:
  title: Dasha BlackBox Agent API
  description: API for managing AI agents and calls
  contact:
    name: DashaAI Team
    email: support@dasha.ai
  version: v1
servers:
  - url: https://blackbox.dasha.ai
    description: Dasha BlackBox Agent API
security:
  - {}
  - {}
tags:
  - name: ActivityLogs
  - name: Agents
  - name: CallResults
  - name: Calls
  - name: Chats
  - name: CustomerData
  - name: Mcp
  - name: Media
  - name: Misc
  - name: PronunciationDictionaries
  - name: Providers
  - name: SipAliases
  - name: SipCredentials
  - name: SipPhoneNumbers
  - name: TextChat
  - name: TwilioProvider
  - name: Voice
  - name: WebhookTest
  - name: WebIntegrations
  - name: WebSocket
    description: WebSocket endpoints for real-time communication
paths:
  /api/v1/webhooks/test:
    post:
      tags:
        - WebhookTest
      summary: Test webhook endpoint
      description: >-
        Tests a webhook endpoint with realistic payload simulation. Sends a test
        payload to the webhook URL

        and validates the response. Returns test results including HTTP status,
        response data, and execution time.
      requestBody:
        description: Webhook configuration and test parameters
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/TestWebhookRequest'
              description: Request body for testing webhooks
          text/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/TestWebhookRequest'
              description: Request body for testing webhooks
          application/*+json:
            schema:
              allOf:
                - $ref: '#/components/schemas/TestWebhookRequest'
              description: Request body for testing webhooks
      responses:
        '200':
          description: Webhook test completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookTestResponse'
        '400':
          description: Invalid configuration or validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Authentication failed or API key is missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Access denied to webhook testing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: Server error occurred during webhook test
components:
  schemas:
    TestWebhookRequest:
      required:
        - webHook
        - webhookType
      type: object
      properties:
        webHook:
          allOf:
            - $ref: '#/components/schemas/WebHook'
          description: >-
            Webhook configuration for HTTP callbacks. Defines the URL endpoint
            to call, custom HTTP headers, and request customization settings for
            sending event data or tool invocations to external systems.
        webhookType:
          allOf:
            - $ref: '#/components/schemas/WebHookPayloadType'
          description: >-
            Type of webhook event being sent. Identifies which stage of the call
            lifecycle or which conversation event triggered the webhook
            notification. Each type corresponds to a specific payload structure
            with event-relevant data.
        toolName:
          type: string
          description: Name of the tool being called (required for tool webhooks)
          nullable: true
        toolArguments:
          type: object
          additionalProperties: {}
          description: Tool arguments (required for tool webhooks)
          nullable: true
        agentAdditionalData:
          type: object
          additionalProperties: {}
          description: Agent additional data for the test
          nullable: true
        callAdditionalData:
          type: object
          additionalProperties: {}
          description: Call additional data for the test
          nullable: true
      additionalProperties: false
      description: Request body for testing webhooks
    WebhookTestResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the webhook test was successful
        httpStatus:
          type: integer
          description: HTTP status code returned by the webhook endpoint
          format: int32
          nullable: true
        httpStatusText:
          type: string
          description: HTTP status text returned by the webhook endpoint
          nullable: true
        responseData:
          description: Response data from the webhook endpoint
          nullable: true
        validationResult:
          allOf:
            - $ref: '#/components/schemas/WebhookValidationResult'
          description: Validation result for start webhook responses
          nullable: true
        error:
          type: string
          description: Error message if the test failed
          nullable: true
        timeTaken:
          type: integer
          description: Time taken to execute the webhook test in milliseconds
          format: int64
      additionalProperties: false
      description: Response for webhook tests
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    WebHook:
      required:
        - url
      type: object
      properties:
        url:
          type: string
          description: >-
            Webhook endpoint URL to send HTTP requests to. The system will POST
            data to this URL when the webhook is triggered.
          format: uri
        headers:
          type: object
          additionalProperties:
            type: string
          description: >-
            Custom HTTP headers to include with webhook requests. Useful for
            authentication, API keys, or passing additional metadata to the
            receiving endpoint.
          nullable: true
        customSettings:
          allOf:
            - $ref: '#/components/schemas/CustomWebhookSettings'
          description: >-
            Custom webhook request settings including HTTP method, query
            parameters, and body format configuration. Allows full control over
            how the webhook request is constructed and sent.
          default: null
          nullable: true
      additionalProperties: false
      description: >-
        Webhook configuration for HTTP callbacks. Defines the URL endpoint to
        call, custom HTTP headers, and request customization settings for
        sending event data or tool invocations to external systems.
    WebHookPayloadType:
      enum:
        - UnknownWebHookPayload
        - StartWebHookPayload
        - FailedWebHookPayload
        - CompletedWebHookPayload
        - CallDeadLineWebHookPayload
        - TransferWebHookPayload
        - ToolWebHookPayload
      type: string
      description: >-
        Type of webhook event being sent. Identifies which stage of the call
        lifecycle or which conversation event triggered the webhook
        notification. Each type corresponds to a specific payload structure with
        event-relevant data.
    WebhookValidationResult:
      type: object
      properties:
        isValid:
          type: boolean
          description: Whether the response is valid
        errors:
          type: array
          items:
            type: string
          description: Validation errors if any
          nullable: true
      additionalProperties: false
      description: Validation result for webhook responses
    CustomWebhookSettings:
      required:
        - httpMethod
      type: object
      properties:
        httpMethod:
          allOf:
            - $ref: '#/components/schemas/HttpMethod'
          description: >-
            HTTP method to use for the webhook request. Determines whether the
            request uses GET, POST, PUT, PATCH, or DELETE. POST is the most
            common choice for webhook notifications.
        queryParams:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: >-
            Query string parameters to append to the webhook URL. Each parameter
            can have multiple values. These parameters are URL-encoded and added
            to the request URL as key=value pairs separated by ampersands.
          nullable: true
        bodyFormat:
          oneOf:
            - $ref: '#/components/schemas/BodyTextFormat'
            - $ref: '#/components/schemas/BodyJSONFormat'
            - $ref: '#/components/schemas/BodyFormFormat'
          description: >-
            Format configuration for the request body. Specifies how the webhook
            payload is encoded and what Content-Type header is sent. Supports
            JSON, plain text, and form-encoded formats for compatibility with
            different endpoint requirements.
          default: null
          nullable: true
      additionalProperties: false
      description: >-
        Custom request settings for webhook HTTP calls. Allows full control over
        how webhook requests are constructed including the HTTP method, URL
        query parameters, and request body formatting. These settings enable
        integration with REST APIs and services that require specific request
        formats.
    HttpMethod:
      enum:
        - GET
        - POST
        - PUT
        - PATCH
        - DELETE
      type: string
      description: >-
        HTTP method to use for webhook requests. Determines how the webhook data
        is sent to the target endpoint. POST is the most common choice for
        sending event data, while GET, PUT, PATCH, and DELETE can be used for
        REST API integrations that require specific HTTP verbs.
    BodyTextFormat:
      allOf:
        - $ref: '#/components/schemas/BodyFormat'
        - required:
            - template
            - type
          type: object
          properties:
            type:
              enum:
                - Text
              type: string
              description: Format type identifier. Always returns Text for this format.
              readOnly: true
            template:
              minLength: 1
              type: string
              description: >-
                Text template defining the structure of the request body. Can
                include placeholders that are replaced with actual webhook
                payload values. The template is sent with Content-Type
                text/plain.
          additionalProperties: false
      description: >-
        Plain text body format using a template string. Allows embedding webhook
        payload values into a custom text template. Useful for integrating with
        systems that expect plain text payloads or custom string formats.
    BodyJSONFormat:
      allOf:
        - $ref: '#/components/schemas/BodyFormat'
        - required:
            - type
          type: object
          properties:
            type:
              enum:
                - Json
              type: string
              description: Format type identifier. Always returns Json for this format.
              readOnly: true
            template:
              type: array
              items:
                $ref: '#/components/schemas/BodyFormatValue'
              description: >-
                List of field mappings defining which values to extract from the
                webhook payload and where to place them in the output JSON
                object. Each mapping specifies a JSON path in the payload and
                where to put the value in the result.
              nullable: true
          additionalProperties: false
      description: >-
        JSON body format using field mappings from the webhook payload.
        Constructs a JSON object by extracting values from the payload using
        JSON path expressions. Sends the result with Content-Type
        application/json. The most common format for modern API integrations.
    BodyFormFormat:
      allOf:
        - $ref: '#/components/schemas/BodyFormat'
        - required:
            - type
          type: object
          properties:
            type:
              enum:
                - Form
              type: string
              description: Format type identifier. Always returns Form for this format.
              readOnly: true
            template:
              type: array
              items:
                $ref: '#/components/schemas/BodyFormatValue'
              description: >-
                List of field mappings defining which values to extract from the
                webhook payload and how to encode them as form fields. Each
                mapping specifies a JSON path in the payload and the
                corresponding form field name.
              nullable: true
          additionalProperties: false
      description: >-
        Form-encoded body format using field mappings from the webhook payload.
        Constructs URL-encoded form data by extracting values from the payload
        using JSON path expressions. Sends the result with Content-Type
        application/x-www-form-urlencoded. Used for integrating with systems
        that expect traditional HTML form submissions.
    BodyFormat:
      required:
        - type
      type: object
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/BodyFormatEnum'
          description: >-
            Format type discriminator indicating which body format
            implementation is used. Determines whether the payload is sent as
            text, JSON, or form data.
          readOnly: true
      additionalProperties: false
      description: >-
        Base class for webhook request body format configurations. Defines how
        the webhook payload is encoded and structured. Concrete implementations
        include text templates, JSON object mapping, and form-encoded data.
    BodyFormatValue:
      required:
        - jsonPath
      type: object
      properties:
        jsonPath:
          minLength: 1
          type: string
          description: >-
            JSON path in the output where the extracted value should be placed.
            For JSON format, this defines the structure of the output object.
            For form format, this is the form field name.
        argumentJsonPath:
          type: string
          description: >-
            JSON path in the webhook payload to extract the value from. When
            specified, the value at this path in the source payload is copied to
            the JsonPath location in the output. If not specified, the
            DefaultValue is used instead.
          nullable: true
        defaultValue:
          description: >-
            Default value to use when ArgumentJsonPath is not specified or when
            the path doesn't exist in the payload. Allows providing fallback
            values to ensure the output always has required fields populated.
          nullable: true
      additionalProperties: false
      description: >-
        Field mapping configuration for extracting values from webhook payloads.
        Defines how to extract a value from the source payload using JSON path
        and where to place it in the output, with support for default values
        when the source path doesn't exist.
    BodyFormatEnum:
      enum:
        - Text
        - Json
        - Form
      type: string
      description: >-
        Content format for the webhook request body. Determines how the webhook
        payload is encoded and what Content-Type header is sent. Different
        formats are appropriate for different receiving endpoints and
        integration requirements.

````