> ## Documentation Index
> Fetch the complete documentation index at: https://docs.permutive.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom Classifications via Webhook
> How to bring your own content classification data into Permutive using the Webhook (Custom) provider
## Overview
The Webhook (Custom) provider lets you connect Permutive to your own content classification system. Permutive calls an HTTPS endpoint you control to retrieve classifications and taxonomy definitions, giving you full flexibility to use an in-house or third-party classification system that is not available as a native provider.
**Prerequisites:**
* Access to the Permutive Dashboard with admin permissions
* A publicly reachable HTTPS endpoint that implements the two request types described below
* The Webhook (Custom) provider enabled for your workspace (contact your Customer Success Manager)
## How It Works
Permutive calls your endpoint with two types of POST request:
* **Classifications request** — sent each time Permutive needs to classify a URL. Your endpoint returns the classification results for that URL.
* **Taxonomies request** — sent to retrieve the structure of any custom taxonomies your classifications reference. Only required if you use custom (non-standard) taxonomies.
Both requests are sent to the same endpoint URL you configure in the dashboard.
## Enabling and Configuring the Provider
In the Permutive Dashboard, go to *Contextual > Catalog*.
Find the Webhook (Custom) provider in the catalog. If it is not visible, contact your Customer Success Manager to have it enabled for your workspace.
Toggle the provider on to enable it.
Set the following provider-specific fields:
| Setting | Description |
| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Endpoint** | The URL Permutive will call to request classifications and taxonomies. Must be a publicly reachable HTTPS URL. |
| **Standard Taxonomies** | The standard taxonomies your endpoint may return in classification responses. Select any combination of IAB 2.0, IAB 2.2, and IAB 3.0. Leave empty if you use only custom taxonomies. |
Save the provider settings. Permutive will begin calling your endpoint when pages are classified.
**Optimizing quota usage**: Use the Selective Classifications Threshold in the provider settings to restrict classification calls to high-traffic URLs. This reduces unnecessary calls to your endpoint and focuses your classifications where they have the most impact.
## Endpoint Contract — Classification Requests
When Permutive needs to classify a URL, it sends the following POST request to your endpoint:
```json theme={"dark"}
{
"type": "classify",
"url": "http://example.com"
}
```
Your endpoint must respond with a JSON object in this format:
```json theme={"dark"}
{
"classifications": [
{
"value": "201",
"type": "categories",
"confidence": 0.72,
"taxonomy": "iab_2.0"
}
]
}
```
### Response Fields
| Field | Type | Required | Description |
| :------------------------------ | :--------------------- | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `classifications` | Array of objects | Yes | List containing all classifications for the current URL. |
| `classifications[#].value` | String | Yes | The classification value. If the type is `categories` and you use a standard taxonomy, this must exactly match the IAB category ID. |
| `classifications[#].type` | String | Yes | Must be one of: `categories`, `keywords`, `entities`, `sentiment`, `emotion`, `concepts`. |
| `classifications[#].confidence` | Number between 0 and 1 | No | Include this if you have a confidence rating for your classification. |
| `classifications[#].taxonomy` | String | Only for `categories` | Only include if the type is `categories`. If you selected Standard Taxonomies in the dashboard, this must match `iab_2.0`, `iab_2.2`, or `iab_3.0`. Otherwise it should match the ID of your custom taxonomy. |
**Supported dimension types**: The Webhook provider supports all dimension types — `categories`, `keywords`, `entities`, `concepts`, `sentiment`, and `emotion` — but the types actually available in Permutive depend on what your endpoint returns.
## Endpoint Contract — Taxonomy Requests
When Permutive encounters a `taxonomy` value in a classification response that does not match a standard taxonomy, it calls your endpoint to retrieve the taxonomy definition:
```json theme={"dark"}
{
"type": "taxonomies"
}
```
Your endpoint must respond with an array of taxonomy objects. If you do not use any custom taxonomies, return an empty array (`[]`).
```json theme={"dark"}
[
{
"id": "my_custom_taxonomy",
"name": "My Custom Taxonomy",
"url": "http://example.com",
"values": [
{
"id": "10",
"name": "Books",
"parent": null
},
{
"id": "123",
"name": "Comic Books",
"parent": "10"
}
]
}
]
```
### Response Fields
| Field | Type | Required | Description |
| :-------------- | :--------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------- |
| `id` | String | Yes | A unique identifier for your taxonomy. This must match the `taxonomy` value you return in classification responses for categories. |
| `name` | String | Yes | Display name of your taxonomy. |
| `url` | String | No | Optional; a URL with more information on your taxonomy. |
| `values` | Array of objects | Yes | The list of entries in your taxonomy. |
| `values.id` | String | Yes | The ID of an entry in your taxonomy. This must match the `value` you return for categories. |
| `values.name` | String | Yes | The display name of the category — this is what will be shown in the dashboard. |
| `values.parent` | String | No | Optional; if this is a sub-category, the `id` of the parent category. |
Your endpoint can return classifications that reference both standard and custom taxonomies in the same response. For example:
```json theme={"dark"}
{
"classifications": [
{
"value": "201",
"type": "categories",
"confidence": 0.85,
"taxonomy": "iab_2.0"
},
{
"value": "123",
"type": "categories",
"confidence": 0.70,
"taxonomy": "my_custom_taxonomy"
},
{
"value": "sport",
"type": "keywords",
"confidence": 0.90
}
]
}
```
In this case, ensure that `iab_2.0` is listed under Standard Taxonomies in the dashboard configuration, and that `my_custom_taxonomy` is returned by your taxonomies endpoint with a matching `id`.
## Custom Classifications
You can use the Webhook provider to import custom content classifications into Permutive. If you need to discuss your classification requirements or explore alternative approaches, contact your Customer Success Manager.
## Next Steps
Configure general provider settings such as domains and quota
Test how your webhook endpoint classifies content
Build audience segments using your custom classifications
Return to product overview