Push API events

Examples

Select a tab to see each example. Both show a subscription with Fetch Entity enabled.

{
  "collection": [
    {
      "metadata": {
        "performer": "[email protected]",
        "performer_name": "API User",
        "change_time_in_utc": "2026-04-05 10:15:30.000",
        "account_id": "acme-advertising",
        "numeric_account_id": 789012
      },
      "changed_entity_fields": {
        "status": "PAUSED",
        "daily_cap": 500.0
      },
      "previous_entity_fields": {
        "status": "RUNNING",
        "daily_cap": 1000.0
      },
      "entity": {
        "id": 456789,
        "name": "Summer Sale Campaign",
        "status": "PAUSED",
        "daily_cap": 500.0,
        "cpc": 0.35,
        "start_date": "2026-03-01",
        "end_date": "2026-06-30",
        "branding_text": "ACME Corp"
      }
    }
  ]
}

{
  "collection": [
    {
      "metadata": {
        "performer": "review-system",
        "performer_name": "Content Review",
        "change_time_in_utc": "2026-04-05 12:45:00.000",
        "account_id": "acme-advertising",
        "numeric_account_id": 789012
      },
      "changed_entity_fields": {
        "approval_state": "APPROVED"
      },
      "previous_entity_fields": {
        "approval_state": "PENDING"
      },
      "entity": {
        "id": 334455,
        "url": "https://www.example.com/landing-page",
        "thumbnail_url": "https://cdn.example.com/image.jpg",
        "description": "Summer Sale - 50% Off",
        "status": "RUNNING",
        "is_active": true,
        "approval_state": "APPROVED"
      }
    }
  ]
}

Overview

Taboola sends every Push API event to your endpoint as a POST request with a JSON body.

The body is a collection structure: everything sits inside a collection array, which always holds exactly one Event object. Taboola sends one request per change.

🚧
Empty values are omitted
A field with no value is left out of the JSON entirely - it is never sent as null. Read every optional field below as "the key may be missing".

Event object

The object in the collection array describes a single change.

Name	Modifiers & Defaults	Type	Description
metadata	Always present	Metadata Object Notes: See Metadata object	Context about the change: who made it, when, and on which account.
changed_entity_fields	Always present	Object Notes: Keys are entity field names May be `{}`	Only the modified fields, with their new values.
previous_entity_fields	Always present	Object Notes: Keys are entity field names May be `{}`	Only the modified fields, with their previous values.
entity	Always present	Object Notes: Identifiers only, unless Fetch Entity is enabled	The entity the change occurred on, after the change. With Fetch Entity enabled on the subscription, it carries the full entity.

Metadata object

Name	Modifiers & Defaults	Type	Description
performer	Always present	String	User ID of the person or system that made the change.
performer_name	Optional	String Notes: Key omitted when unset	Display name of the performer.
change_time_in_utc	Always present	String Format: `yyyy-MM-dd HH:mm:ss.SSS`	Timestamp of the change, in UTC. Use this to sequence events - delivery order is not guaranteed.
account_id	Optional	String Notes: Key omitted when unset	The account's alphabetic identifier.
numeric_account_id	Always present	Long	The account's numeric identifier.

Headers

Every webhook POST request includes the following headers:

Header	Description
`Content-Type`	Always `application/json`.
`Taboola-Signature`	HMAC-SHA256 signature of the request body, computed with the `client_secret` of the API key on the subscription. See Validating the signature.

Push API covers subscriptions, endpoint requirements, and signature validation.

Push API events

Examples

Overview

Empty values are omitted

Event object

Metadata object

Headers

Related