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

# Send a webhook test

> Send one subscribed sample event and return its HTTP outcome and latency.

Choose a subscribed type or omit it to use the first subscribed type in catalogue order.

The delivered envelope has type webhook.test and data containing sampleType and sample. Tests are limited to five per minute per destination.

A delivery failure is an outcome with ok: false, rather than a problem response. Paused destinations return destination\_paused.

## Related pages

* [Authentication](https://hellotars.com/docs/developer/authentication.md)


## OpenAPI

````yaml api-reference/openapi.json POST /api/v1/webhooks/{id}/test
openapi: 3.1.0
info:
  title: Tars API
  version: '1'
  description: >-
    Start conversations, send messages, manage contacts, send campaign messages,
    place and read calls, and manage webhook destinations.
servers:
  - url: https://us.api.hellotars.com
    description: United States
  - url: https://eu.api.hellotars.com
    description: European Union
  - url: https://in.api.hellotars.com
    description: India
  - url: https://qa.api.hellotars.com
    description: Qatar
security:
  - bearerAuth: []
tags:
  - name: Conversations
    description: Start conversations at a chat agent's trigger step.
  - name: Messages
    description: Send channel messages as a chat agent.
  - name: Contacts
    description: Read and manage contacts.
  - name: Campaigns
    description: Send webhook campaign messages.
  - name: Calls
    description: Place, read and manage phone calls.
  - name: Agents
    description: Read chat agents and voice agents.
  - name: Phone numbers
    description: Read your phone numbers.
  - name: Artefacts
    description: Download call recordings.
  - name: Webhooks
    description: Manage webhook destinations.
paths:
  /api/v1/webhooks/{id}/test:
    post:
      tags:
        - Webhooks
      summary: Send a test event
      description: >-
        Sends a signed webhook.test event with a sample of one of the
        destination's events in data. The outcome of the delivery is in the
        result.


        Requires the Manage webhooks permission (`webhooks:manage`).
      operationId: testWebhookDestination
      parameters:
        - name: id
          in: path
          required: true
          description: The id.
          schema:
            type: string
            minLength: 1
            maxLength: 128
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DestinationTest'
      responses:
        '200':
          description: The test delivery result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DestinationTestResult'
        '400':
          description: validation_failed, invalid_json
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: unauthorized, invalid_key
          headers:
            WWW-Authenticate:
              schema:
                const: Bearer
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: organization_inactive, billing_locked, permission_missing
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: not_found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '405':
          description: method_not_allowed
          headers:
            Allow:
              description: The methods this path accepts.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: wrong_region
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '413':
          description: payload_too_large
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: rate_limited
          headers:
            Retry-After:
              description: Whole seconds to wait before retrying.
              schema:
                type: integer
                minimum: 1
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: internal_error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
        - bearerAuth: []
components:
  schemas:
    DestinationTest:
      type: object
      description: The event to send a sample of.
      additionalProperties: false
      properties:
        type:
          type: string
          enum:
            - conversation.started
            - conversation.ended
            - conversation.analyzed
            - call.transcript_updated
            - call.transfer_ringing
            - call.transfer_connected
            - call.transfer_bridged
            - call.transfer_failed
            - call.transfer_cancelled
            - call.guardrail_triggered
            - call.sms_sent
            - call.continued_in_chat
            - handoff.requested
            - handoff.accepted
            - handoff.unmet
            - handoff.completed
            - campaign.message_sent
            - campaign.message_delivered
            - campaign.message_read
            - campaign.message_replied
            - campaign.message_failed
            - campaign.completed
            - contact.created
            - contact.updated
          description: One of the destination's events. Defaults to its first event.
    DestinationTestResult:
      oneOf:
        - type: object
          description: The destination answered with a 2xx status.
          properties:
            ok:
              const: true
            status:
              type: integer
            latencyMs:
              type: number
          required:
            - ok
            - status
            - latencyMs
        - type: object
          description: The delivery failed.
          properties:
            ok:
              const: false
            error:
              type: string
            status:
              type: integer
            latencyMs:
              type: number
          required:
            - ok
            - error
    Problem:
      type: object
      description: >-
        RFC 9457 problem details. Clients switch on code, never on title or
        detail.
      properties:
        title:
          type: string
          description: The catalogue title of code.
        status:
          type: integer
          description: The HTTP status.
        detail:
          type: string
          description: A sentence about this failure, for a developer.
        instance:
          type: string
          description: The request id (req_…). Quote it when you contact support.
        code:
          type: string
          enum:
            - invalid_json
            - validation_failed
            - variable_key_not_allowed
            - invalid_variable_value
            - cursor_expired
            - cursor_mismatch
            - campaign_mode_invalid
            - unauthorized
            - invalid_key
            - session_invalid
            - insufficient_balance
            - organization_inactive
            - billing_locked
            - permission_missing
            - resource_not_allowed
            - entitlement_missing
            - origin_not_allowed
            - recaptcha_failed
            - consent_revoked
            - us_marketing_blocked
            - channel_test_mode
            - quota_exceeded
            - forbidden
            - not_found
            - method_not_allowed
            - wrong_region
            - conflict
            - contact_exists
            - idempotency_key_reuse
            - agent_unavailable
            - call_not_live
            - call_still_live
            - call_content_deleted
            - invalid_state
            - campaign_paused
            - template_version_drift
            - channel_unavailable
            - artefact_deleted
            - campaign_gone
            - payload_too_large
            - template_not_approved
            - channel_misconfigured
            - channel_reauth_required
            - meta_rejected
            - rate_limited
            - concurrency_limit_reached
            - worker_busy
            - meta_rate_limited
            - internal_error
            - upstream_unavailable
            - meta_unavailable
            - worker_not_deployed
            - worker_unavailable
        retryable:
          type: boolean
          description: true when the same request can succeed later.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationIssue'
        required:
          type: string
          description: The permission the key lacks (permission_missing).
        region:
          type: string
          description: The organization's region (wrong_region).
        field:
          type: string
          enum:
            - email
            - phone
        contactId:
          type: string
          description: The contact that already has the email or phone.
        callId:
          type: string
        reason:
          type: string
      required:
        - title
        - status
        - detail
        - instance
        - code
        - retryable
    ValidationIssue:
      type: object
      description: One field that failed validation.
      properties:
        path:
          type: string
          description: >-
            Dotted path of the field (template.parameters.body.0), the query
            parameter name, or an empty string for the whole body.
        code:
          type: string
          description: >-
            Why the field failed, for example required, unknown_field,
            out_of_range or template_param_missing.
        message:
          type: string
      required:
        - path
        - code
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An API key (`tars_sk_…`) sent as `Authorization: Bearer <key>`. Each
        operation names the permission it needs. Create keys in Settings →
        Integrations → API keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.