To avoid continually polling the Verity Page endpoint for classification responses, clients can create a webhook to listen for results on a Verity callback URL.
To integrate with Verity, the webhook target server must:
Be able to receive HTTP/HTTPS POST requests over the internet.
Respond to Verity with an HTTP 2XX status code.
Send responses to Verity within 5 seconds.
Note: No data is required in webhook responses to Verity.
These steps walk through a Verity page classification request with webhook integration.
Step 1 – Expose web service
First, expose your web service, for example:
Step 2 – Create page classification request
Create a Verity page classification request, for example:
Step 3 – Add callbackUrl parameter with webhook address
Add a callBackUrl parameter with the webhook address to the page request. The webhook URL must be properly URL-encoded. For example:
&callBackUrl=https%3A%2F%2Fverity-webhook.domain.com%2Fresults |
Step 4 – Submit GET page classification request
Submit the GET request via curl:
curl -H 'x-api-key: <YOUR_API_KEY_HERE>’ `https://verity-api.gumgum.com/page/classify?pageUrl=https%3A%2F%2Ftest.iab12.com%2F1&callBackUrl=https%3A%2F%2Fverity-webhook.domain.com%2Fresults` |
Verity issues an HTTP Status Code 202 (ACCEPTED) to indicate that the request has been initiated. The status field in the response JSON within the data payload updates to INITIATED.
Note: Verity response time SLAs are under development.
Step 5 – Verity POSTs response to webhook URL
After successfully processing the request, Verity initiates an HTTP/HTTPS POST to the webhook URL with the response JSON data, for example:
{
"dataAvailable": true,
"status": "PROCESSED",
"pageUrl": "https://aragonresearch.com/cisco-google-and-zoom-enhance-free-meetings-to-assist-with-coronavirus",
"verityData": {
"languageCode": "en",
"iab": {
"v1": [
{
"id": "IAB19",
"category": "Technology & Computing",
"score": 0.58
},
{
"id": "IAB19-23",
"category": "Net Conferencing",
"score": 0.15
},
{
"id": "IAB19-8",
"category": "Computer Networking",
"score": 0.12
},
{
"id": "IAB19-18",
"category": "Internet Technology",
"score": 0.1
}
],
"v2": [
{
"id": "596",
"category": "Technology & Computing",
"score": 0.45
},
{
"id": "52",
"category": "Business and Finance",
"score": 0.29
},
{
"id": "607",
"category": "Web Conferencing",
"score": 0.1,
"parent": {
"id": "602",
"category": "Computer Software and Applications",
"parent": {
"id": "599",
"category": "Computing",
"parent": {
"id": "596",
"category": "Technology & Computing"
}
}
}
},
{
"id": "600",
"category": "Computer Networking",
"score": 0.06,
"parent": {
"id": "599",
"category": "Computing",
"parent": {
"id": "596",
"category": "Technology & Computing"
}
}
},
{
"id": "53",
"category": "Business",
"score": 0.05,
"parent": {
"id": "52",
"category": "Business and Finance"
}
}
]
},
"keywords": [
"covid",
"coronavirus",
"covid-19",
"pandemic",
"logmein",
"coronavirus cisco",
"large coronavirus outbreak",
"cisco",
"zoom",
"logmein offers free remote",
"free webex cisco",
"google hangouts",
"google",
"cisco makes",
"aragon",
"zoom removes",
"google offers premium features",
"zoom enhance free meetings",
"enhance"
],
"safe": false,
"threats": [
{
"id": "GGT9",
"category": "Medical",
"confidence": "HIGH"
}
],
"events": [],
"sentiments": [
{
"sentiment": "neutral",
"score": 0.73
},
{
"sentiment": "positive",
"score": 0.24
},
{
"sentiment": "negative",
"score": 0.03
}
],
"processedAt": "2020-10-01T01:15:09.982Z"
}
}
{ "dataAvailable": true, "status": "PROCESSED", "pageUrl": "https://aragonresearch.com/cisco-google-and-zoom-enhance-free-meetings-to-assist-with-coronavirus", "verityData": { "languageCode": "en", "iab": { "v1": [ { "id": "IAB19", "category": "Technology & Computing", "score": 0.58 }, { "id": "IAB19-23", "category": "Net Conferencing", "score": 0.15 }, { "id": "IAB19-8", "category": "Computer Networking", "score": 0.12 }, { "id": "IAB19-18", "category": "Internet Technology", "score": 0.1 } ], "v2": [ { "id": "596", "category": "Technology & Computing", "score": 0.45 }, { "id": "52", "category": "Business and Finance", "score": 0.29 }, { "id": "607", "category": "Web Conferencing", "score": 0.1, "parent": { "id": "602", "category": "Computer Software and Applications", "parent": { "id": "599", "category": "Computing", "parent": { "id": "596", "category": "Technology & Computing" } } } }, { "id": "600", "category": "Computer Networking", "score": 0.06, "parent": { "id": "599", "category": "Computing", "parent": { "id": "596", "category": "Technology & Computing" } } }, { "id": "53", "category": "Business", "score": 0.05, "parent": { "id": "52", "category": "Business and Finance" } } ] }, "keywords": [ "covid", "coronavirus", "covid-19", "pandemic", "logmein", "coronavirus cisco", "large coronavirus outbreak", "cisco", "zoom", "logmein offers free remote", "free webex cisco", "google hangouts", "google", "cisco makes", "aragon", "zoom removes", "google offers premium features", "zoom enhance free meetings", "enhance" ], "safe": false, "threats": [ { "id": "GGT9", "category": "Medical", "confidence": "HIGH" } ], "events": [], "sentiments": [ { "sentiment": "neutral", "score": 0.73 }, { "sentiment": "positive", "score": 0.24 }, { "sentiment": "negative", "score": 0.03 } ], "processedAt": "2020-10-01T01:15:09.982Z" } } |
Step 6 – Webhook target server sends a successful response status code
The webhook target server sends a successful response status code (2XX) within the HTTP connection timeout of 5 seconds.