Custom Classifications via Webhook

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

Navigate to Catalog

In the Permutive Dashboard, go to Contextual > Catalog.

Locate the Webhook (Custom) provider

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.

Enable the provider

Toggle the provider on to enable it.

Configure provider settings

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 your configuration

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:

{
  "type": "classify",
  "url": "http://example.com"
}

Your endpoint must respond with a JSON object in this format:

{
  "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:

{
  "type": "taxonomies"
}

Your endpoint must respond with an array of taxonomy objects. If you do not use any custom taxonomies, return an empty array ([]).

[
  {
    "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.

Show Example: mixing standard and custom taxonomies

Your endpoint can return classifications that reference both standard and custom taxonomies in the same response. For example:

{
  "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.