************************************************
Track Webhook
************************************************

Use this API to manage the webhook override for one track.

The per-track webhook is optional. If it is not configured, or if it has ``inherit`` set to ``true``, Xobin uses the company-wide default from Track Webhook Settings.

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

Use **Track Webhook Settings** to set one default webhook for every track.

Use **Track Webhook** when a specific track needs different delivery behavior, for example a different URL for one job opening.

.. 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/<track_id>/webhook``
     - Returns the track override, company default, and effective config that will be used.
   * - ``PUT``
     - ``/tracks/<track_id>/webhook``
     - Replaces the full per-track override.
   * - ``PATCH``
     - ``/tracks/<track_id>/webhook``
     - Updates only supplied fields in the per-track override.
   * - ``DELETE``
     - ``/tracks/<track_id>/webhook``
     - Removes the per-track override so the track falls back to the company default.

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

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

.. code-block::

    GET /tracks/<track_id>/webhook

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

No request body is required.

Response
--------

**200 OK**

.. code-block:: json

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

Response meaning
----------------

.. list-table::
   :header-rows: 1
   :widths: 24 76

   * - Field
     - Meaning
   * - ``webhook``
     - The override saved directly on this track. This can be ``null`` when no override is configured.
   * - ``company_default``
     - The company-wide default from Track Webhook Settings. This can be ``null`` when no default exists.
   * - ``effective``
     - The config Xobin will actually use when this track receives a completed applicant. This is the track override when ``inherit`` is ``false``; otherwise it is the company default.

``PUT`` Track Webhook
=====================

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

.. code-block::

    PUT /tracks/<track_id>/webhook

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

``PUT`` replaces the complete per-track override.

.. code-block:: json

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

Response
--------

**200 OK** - Same response shape as ``GET``.

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

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

.. code-block::

    PATCH /tracks/<track_id>/webhook

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

``PATCH`` updates only the supplied fields. For example, this makes the track inherit the company default:

.. code-block:: json

    {
        "webhook": {
            "inherit": true
        }
    }

Response
--------

**200 OK**

.. code-block:: json

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

``DELETE`` Track Webhook
========================

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

.. code-block::

    DELETE /tracks/<track_id>/webhook

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

No request body is required.

Response
--------

**200 OK** - The track override is removed. ``effective`` shows the company default if one exists.

.. code-block:: json

    {
        "track_id": 12345,
        "webhook": null,
        "company_default": {
            "status": true,
            "url": "https://example.com/xobin/default",
            "inherit": false,
            "has_secret": true
        },
        "effective": {
            "status": true,
            "url": "https://example.com/xobin/default",
            "inherit": false,
            "has_secret": true
        }
    }

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

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

   * - Field
     - Type
     - Description
   * - ``status``
     - boolean
     - Enables or disables this track override.
   * - ``url``
     - string
     - HTTPS endpoint that receives the signed ``tracks.applicant.completed`` payload. Required when ``status`` is ``true`` and ``inherit`` is ``false``.
   * - ``secret``
     - string
     - Optional signing secret. If omitted, your company API key is used to sign the webhook payload.
   * - ``inherit``
     - boolean
     - When ``true``, Xobin ignores this track override for delivery and uses the company default.

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.
   * - ``404``
     - Track not found
     - The specified track does not exist in the API key's account.