Webhooks

This section covers TollBit's webhooks model, including how to validate a webhook from TollBit and getting a history of webhooks calls.

The Webhooks model

Webhooks allow your application to receive real-time notifications when content becomes available from TollBit publishers. Instead of polling our API repeatedly, you can register a webhook endpoint and we’ll push events to you as they happen.

Name
sourceCuid
Type
string
Description
Account identifier for the property.
Name
sourceHost
Type
string
Description
Domain host of the content
Name
contentUrl
Type
string
Description
The specific page url for the intended content to access.
Name
timestamp
Type
int
Description
UTC timestamp of when content was appended.
Name
notificationType
Type
string
Description
Values here would either be CREATED or UPDATED.

Each Item in Items has the shape:

Response

    {
        "sourceCuid": "rd4mezz10lifxlk90d9nd38p",
	    "sourceHost": "pioneervalleygazette.com",
	    "contentUrl": "https://pioneervalleygazette.com/article/bubble-fairy",
	    "timestamp": "2025-09-30T23:08:40.620435262Z",
	    "notificationType": "CREATED"
    }

Validating a Webhook

The following attributes allow you to validate the webhook you’re receiving from a subscribed endpoint.

Attributes

IP Range: the service responsible for making these webhook deliveries uses a NAT Gateway with only a single public IP address: 52.22.183.94 . All Webhooks from us will originate from that IP.
Signature: We use HMACSHA256 to create the signature. The encrypted value is contained within the Authorization Header. The signature consists of only the URL of the webhook url you supplied us, and the key to compute it is the SigningSecret associated with the Subscription (should be obtainable within the UI).
User Agent: There is a User Agent value of "tollbot/1.0" that may be worthwhile to verify.

GET/dev/v1/webhook/history

Get History

In addition to retrieving the webhook, this endpoint allows you to ask for the history of webhooks within an optional lookback window, including specific content URLs and last attempted delivery time and status.

Request Parameters

Name
next-token
Type
optional pagination token
Description
This is an optional pagination token. A given request will return a token to retrieve the next page, if available.
Name
size
Type
int
Description
This is the number of items per page to request. Default of 25. Max of 1000.
Name
days-ago
Type
int
Description
This is the number of days back from current date to retrieve webhook history.

Here is what a standard response would look like:

Response

    {
        "Items": [] // array of response items, defined below
        "nextToken": String // optional continuation token if there are more results
    }

Each Item in Items has the shape:

Item Response

    {
        "subscriptionId": string // id of the Subscription linking recipient org to the publisher
	    "contentUrl": string // url to the content that was updated, e.g. a Time.com URL
	    "deliveryUrl": string // url that Tollbit attempt to send this webhook to
	    "eventType": string // either CREATE or UPDATE
	    "lastAttempt": timestamp // timestamp representing the last time in UTC that Tollbit attempted to send a webhook to the deliveryUrl
	    "lastStatus": int // HTTP status code of the last attempt
	    "numAttempts": int 
    }