************************************************
Track Webhook Settings
************************************************

Use this API to manage the **company-wide default** webhook for track applicant events.

This default webhook is used for every track that does not have its own per-track override. The webhook fires when a candidate applies to a track and is added to the Applied stage with ``invite_status`` set to ``Completed``.

Difference from Track Webhook API
=================================

Use **Track Webhook Settings** when you want one default webhook for all tracks in your account.

Use **Track Webhook** when one specific track should use a different webhook URL, signing secret, or enabled status.

.. warning::

    You must include your API key in the request headers.

Supported methods
=================

.. list-table::
   :header-rows: 1
   :widths: 18 32 50

   * - Method
     - Endpoint
     - What it does
   * - ``GET``
     - ``/tracks/settings/webhooks``
     - Returns the current company-wide default track webhook config.
   * - ``POST``
     - ``/tracks/settings/webhooks``
     - Replaces the full company-wide default config with the supplied payload.
   * - ``PATCH``
     - ``/tracks/settings/webhooks``
     - Updates only the supplied fields and keeps all other existing config values.

``GET`` Track Webhook Settings
==============================

Request URL
-----------

.. code-block::

    GET /tracks/settings/webhooks

Request body
------------

No request body is required.

Response
--------

**200 OK**

.. code-block:: json

    {
        "webhook": {
            "status": true,
            "url": "https://example.com/xobin/track-applicants",
            "inherit": false,
            "has_secret": true
        }
    }

``POST`` Track Webhook Settings
===============================

Request URL
-----------

.. code-block::

    POST /tracks/settings/webhooks

Request body
------------

``POST`` replaces the complete company default webhook config.

.. code-block:: json

    {
        "webhook": {
            "status": true,
            "url": "https://example.com/xobin/track-applicants",
            "secret": "optional-custom-signing-secret"
        }
    }

Response
--------

**200 OK**

.. code-block:: json

    {
        "webhook": {
            "status": true,
            "url": "https://example.com/xobin/track-applicants",
            "inherit": false,
            "has_secret": true
        }
    }

``PATCH`` Track Webhook Settings
================================

Request URL
-----------

.. code-block::

    PATCH /tracks/settings/webhooks

Request body
------------

``PATCH`` updates only the supplied fields. For example, this disables the company default without changing its URL or secret:

.. code-block:: json

    {
        "webhook": {
            "status": false
        }
    }

Response
--------

**200 OK**

.. code-block:: json

    {
        "webhook": {
            "status": false,
            "url": "https://example.com/xobin/track-applicants",
            "inherit": false,
            "has_secret": true
        }
    }

Webhook object
==============

.. list-table::
   :header-rows: 1
   :widths: 20 18 62

   * - Field
     - Type
     - Description
   * - ``status``
     - boolean
     - Enables or disables the default webhook.
   * - ``url``
     - string
     - HTTPS endpoint that receives the signed ``tracks.applicant.completed`` payload. Required when ``status`` is ``true``.
   * - ``secret``
     - string
     - Optional signing secret. If omitted, your company API key is used to sign the webhook payload.

Response fields
===============

.. list-table::
   :header-rows: 1
   :widths: 24 18 58

   * - Field
     - Type
     - Description
   * - ``webhook.status``
     - boolean
     - Whether the company default webhook is enabled.
   * - ``webhook.url``
     - string
     - Current destination URL.
   * - ``webhook.inherit``
     - boolean
     - Always ``false`` for the company default. Inheritance is only used by per-track overrides.
   * - ``webhook.has_secret``
     - boolean
     - ``true`` when a custom secret is stored. The raw secret is never returned.

Error Responses
===============

.. list-table::
   :header-rows: 1
   :widths: 20 30 50

   * - Status Code
     - Error
     - Description
   * - ``400``
     - Bad Request
     - Missing ``webhook`` object or invalid webhook fields.
   * - ``401``
     - Unauthorized
     - API key is missing or invalid.