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

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

GET /tracks/settings/webhooks

Request body

No request body is required.

Response

200 OK

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

POST Track Webhook Settings

Request URL

POST /tracks/settings/webhooks

Request body

POST replaces the complete company default webhook config.

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

Response

200 OK

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

PATCH Track Webhook Settings

Request URL

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:

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

Response

200 OK

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

Webhook object

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

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

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