Event types

Every event Listener sends, where it comes from, and an example payload for each.

1 min read

Subscribe an endpoint to the types below, or to ["*"] for all of them. Every event shares the same envelope:

Field
`id`	`evt_…`. Unique; use it to deduplicate.
`type`	One of the types below.
`api_version`	The API version that shaped `data`.
`created`	When the change happened (ISO 8601, UTC).
`workspace_id`	The workspace it happened in.
`source`	`api`, `app` or `system`. See where events come from.
`data.object`	The resource after the change. For `*.deleted`, its last known state.
`data.changed_fields`	For updates detected in the app: the names of the fields that changed.
`data.previous_attributes`	For updates: old values, when they are known (`status`, `title`, `node_count`, `last_updated`, `connected`, `stale`).
`request`	For `source: "api"`: the `id` and `idempotency_key` of the request that caused it. Otherwise `null`.

The labels next to each type show which sources can produce it. Expand a type to see an example.

The same catalog, with these examples, is served as JSON at GET /v1/event-types (no authentication). Events detected from app changes carry a compact data.object; call the matching GET endpoint when you need the full resource. webhook_endpoint.test is sent only when you ask for it: a * subscription never receives it.

Campaigns

campaign.createdAPIAppA campaign was created.

Example payload

{
  "object": "event",
  "id": "evt_1a2B3c4D5e6F7g8H9i0JkLmN",
  "type": "campaign.created",
  "api_version": "2026-10-14",
  "created": "2026-10-14T09:30:00Z",
  "workspace_id": "uJm8Fq1kT0bYwZ3xA9cD",
  "source": "app",
  "data": {
    "object": {
      "object": "campaign",
      "id": "Xb3kQ9LmT2vWc8Rz1PaE",
      "title": "Acme Coffee Q4 Fall Flight",
      "description": "Host-read mid-rolls plus two YouTube integrations per show.",
      "status": "active",
      "start_date": "2026-10-01",
      "end_date": "2026-12-15",
      "brand": {
        "name": "Acme Coffee",
        "slug": "acme-coffee",
        "domain": "acmecoffee.example",
        "logo": "https://cdn.example.com/acme-coffee.png"
      },
      "goals": {
        "total_views": 2500000,
        "total_budget": 85000
      },
      "cluster_ids": [
        "cluster-6vQ1jWjYcK2mWkQ0dGx3Zp"
      ],
      "total_slots": 12,
      "created_at": "2026-09-22T15:04:11Z",
      "updated_at": "2026-10-14T09:29:58Z",
      "public_url": "https://network.listener.com/northwind-audio/campaigns/Xb3kQ9LmT2vWc8Rz1PaE"
    }
  },
  "request": null
}

campaign.updatedAPIAppA campaign's title, description, dates, brand, goals, slots, linked clusters, exclusions or EMV settings changed.

Example payload

{
  "object": "event",
  "id": "evt_1a2B3c4D5e6F7g8H9i0JkLmN",
  "type": "campaign.updated",
  "api_version": "2026-10-14",
  "created": "2026-10-14T09:30:00Z",
  "workspace_id": "uJm8Fq1kT0bYwZ3xA9cD",
  "source": "app",
  "data": {
    "object": {
      "object": "campaign",
      "id": "Xb3kQ9LmT2vWc8Rz1PaE",
      "title": "Acme Coffee Q4 Fall Flight",
      "description": "Host-read mid-rolls plus two YouTube integrations per show.",
      "status": "active",
      "start_date": "2026-10-01",
      "end_date": "2026-12-15",
      "brand": {
        "name": "Acme Coffee",
        "slug": "acme-coffee",
        "domain": "acmecoffee.example",
        "logo": "https://cdn.example.com/acme-coffee.png"
      },
      "goals": {
        "total_views": 2500000,
        "total_budget": 85000
      },
      "cluster_ids": [
        "cluster-6vQ1jWjYcK2mWkQ0dGx3Zp"
      ],
      "total_slots": 12,
      "created_at": "2026-09-22T15:04:11Z",
      "updated_at": "2026-10-14T09:29:58Z",
      "public_url": "https://network.listener.com/northwind-audio/campaigns/Xb3kQ9LmT2vWc8Rz1PaE"
    },
    "changed_fields": [
      "goals",
      "slots"
    ],
    "previous_attributes": {}
  },
  "request": null
}

campaign.deletedAPIAppA campaign was deleted.

Example payload

{
  "object": "event",
  "id": "evt_1a2B3c4D5e6F7g8H9i0JkLmN",
  "type": "campaign.deleted",
  "api_version": "2026-10-14",
  "created": "2026-10-14T09:30:00Z",
  "workspace_id": "uJm8Fq1kT0bYwZ3xA9cD",
  "source": "app",
  "data": {
    "object": {
      "object": "campaign",
      "id": "Xb3kQ9LmT2vWc8Rz1PaE",
      "title": "Acme Coffee Q4 Fall Flight",
      "deleted": true
    }
  },
  "request": null
}

campaign.status_changedAPIAppA campaign's status (upcoming, active, completed) changed, either set by hand or because its flight started or ended.

Example payload

{
  "object": "event",
  "id": "evt_1a2B3c4D5e6F7g8H9i0JkLmN",
  "type": "campaign.status_changed",
  "api_version": "2026-10-14",
  "created": "2026-10-14T09:30:00Z",
  "workspace_id": "uJm8Fq1kT0bYwZ3xA9cD",
  "source": "app",
  "data": {
    "object": {
      "object": "campaign",
      "id": "Xb3kQ9LmT2vWc8Rz1PaE",
      "title": "Acme Coffee Q4 Fall Flight",
      "description": "Host-read mid-rolls plus two YouTube integrations per show.",
      "status": "active",
      "start_date": "2026-10-01",
      "end_date": "2026-12-15",
      "brand": {
        "name": "Acme Coffee",
        "slug": "acme-coffee",
        "domain": "acmecoffee.example",
        "logo": "https://cdn.example.com/acme-coffee.png"
      },
      "goals": {
        "total_views": 2500000,
        "total_budget": 85000
      },
      "cluster_ids": [
        "cluster-6vQ1jWjYcK2mWkQ0dGx3Zp"
      ],
      "total_slots": 12,
      "created_at": "2026-09-22T15:04:11Z",
      "updated_at": "2026-10-14T09:29:58Z",
      "public_url": "https://network.listener.com/northwind-audio/campaigns/Xb3kQ9LmT2vWc8Rz1PaE"
    },
    "previous_attributes": {
      "status": "upcoming"
    }
  },
  "request": null
}

Clusters

cluster.createdAPIAppAn episode cluster was created (by hand, by the AI cluster builder or by a merge).

Example payload

{
  "object": "event",
  "id": "evt_1a2B3c4D5e6F7g8H9i0JkLmN",
  "type": "cluster.created",
  "api_version": "2026-10-14",
  "created": "2026-10-14T09:30:00Z",
  "workspace_id": "uJm8Fq1kT0bYwZ3xA9cD",
  "source": "app",
  "data": {
    "object": {
      "object": "cluster",
      "id": "cluster-6vQ1jWjYcK2mWkQ0dGx3Zp",
      "show_id": "pQ7sHt2Lw9XcV4bN1mRa",
      "name": "Episode 412: Deadline Day Fallout",
      "internal_title": null,
      "episode_ids": [
        "6vQ1jWjYcK2mWkQ0dGx3Zp"
      ],
      "node_count": 18,
      "is_manual": false,
      "auto_generated": true,
      "created_at": "2026-10-13T18:22:40Z",
      "updated_at": "2026-10-14T09:12:03Z",
      "public_url": "https://listener.com/cluster/pQ7sHt2Lw9XcV4bN1mRa_cluster-6vQ1jWjYcK2mWkQ0dGx3Zp"
    }
  },
  "request": null
}

cluster.updatedAPIAppA cluster's name, internal title, linked episodes, brand collaboration or page customization changed, or nodes were removed.

Example payload

{
  "object": "event",
  "id": "evt_1a2B3c4D5e6F7g8H9i0JkLmN",
  "type": "cluster.updated",
  "api_version": "2026-10-14",
  "created": "2026-10-14T09:30:00Z",
  "workspace_id": "uJm8Fq1kT0bYwZ3xA9cD",
  "source": "app",
  "data": {
    "object": {
      "object": "cluster",
      "id": "cluster-6vQ1jWjYcK2mWkQ0dGx3Zp",
      "show_id": "pQ7sHt2Lw9XcV4bN1mRa",
      "name": "Episode 412: Deadline Day Fallout",
      "internal_title": null,
      "episode_ids": [
        "6vQ1jWjYcK2mWkQ0dGx3Zp"
      ],
      "node_count": 18,
      "is_manual": false,
      "auto_generated": true,
      "created_at": "2026-10-13T18:22:40Z",
      "updated_at": "2026-10-14T09:12:03Z",
      "public_url": "https://listener.com/cluster/pQ7sHt2Lw9XcV4bN1mRa_cluster-6vQ1jWjYcK2mWkQ0dGx3Zp"
    },
    "changed_fields": [
      "name"
    ],
    "previous_attributes": {}
  },
  "request": null
}

cluster.deletedAPIAppA cluster was deleted.

Example payload

{
  "object": "event",
  "id": "evt_1a2B3c4D5e6F7g8H9i0JkLmN",
  "type": "cluster.deleted",
  "api_version": "2026-10-14",
  "created": "2026-10-14T09:30:00Z",
  "workspace_id": "uJm8Fq1kT0bYwZ3xA9cD",
  "source": "app",
  "data": {
    "object": {
      "object": "cluster",
      "id": "cluster-6vQ1jWjYcK2mWkQ0dGx3Zp",
      "show_id": "pQ7sHt2Lw9XcV4bN1mRa",
      "deleted": true
    }
  },
  "request": null
}

cluster.nodes_addedAPIAppContent nodes (clips, posts, videos) were added to a cluster.

Example payload

{
  "object": "event",
  "id": "evt_1a2B3c4D5e6F7g8H9i0JkLmN",
  "type": "cluster.nodes_added",
  "api_version": "2026-10-14",
  "created": "2026-10-14T09:30:00Z",
  "workspace_id": "uJm8Fq1kT0bYwZ3xA9cD",
  "source": "app",
  "data": {
    "object": {
      "object": "cluster",
      "id": "cluster-6vQ1jWjYcK2mWkQ0dGx3Zp",
      "show_id": "pQ7sHt2Lw9XcV4bN1mRa",
      "name": "Episode 412: Deadline Day Fallout",
      "internal_title": null,
      "episode_ids": [
        "6vQ1jWjYcK2mWkQ0dGx3Zp"
      ],
      "node_count": 18,
      "is_manual": false,
      "auto_generated": true,
      "created_at": "2026-10-13T18:22:40Z",
      "updated_at": "2026-10-14T09:12:03Z",
      "public_url": "https://listener.com/cluster/pQ7sHt2Lw9XcV4bN1mRa_cluster-6vQ1jWjYcK2mWkQ0dGx3Zp"
    },
    "previous_attributes": {
      "node_count": 14
    },
    "nodes_added": 4
  },
  "request": null
}

cluster_build.completedAPISystemAn AI cluster build job finished (done, failed or cancelled).

Example payload

{
  "object": "event",
  "id": "evt_1a2B3c4D5e6F7g8H9i0JkLmN",
  "type": "cluster_build.completed",
  "api_version": "2026-10-14",
  "created": "2026-10-14T09:30:00Z",
  "workspace_id": "uJm8Fq1kT0bYwZ3xA9cD",
  "source": "system",
  "data": {
    "object": {
      "object": "cluster_build",
      "job_id": "bld_9Qe2Rk7Tz1",
      "status": "done",
      "scope": {
        "kind": "range",
        "from_date": "2026-10-01",
        "to_date": "2026-10-14",
        "episode_ids": []
      },
      "mode": "auto",
      "source": "mcp",
      "total": 9,
      "done": 9,
      "progress_pct": 100,
      "counts": {
        "built": 6,
        "ready": 2,
        "nothing": 1,
        "failed": 0,
        "skipped": 0
      },
      "credits_used": 41,
      "created_at": "2026-10-14T08:40:00Z"
    }
  },
  "request": null
}

Shows, episodes & data

episode.createdAppA new episode appeared in a show's feed data (stored Spotify, Apple or YouTube episodes).

Example payload

{
  "object": "event",
  "id": "evt_1a2B3c4D5e6F7g8H9i0JkLmN",
  "type": "episode.created",
  "api_version": "2026-10-14",
  "created": "2026-10-14T09:30:00Z",
  "workspace_id": "uJm8Fq1kT0bYwZ3xA9cD",
  "source": "app",
  "data": {
    "object": {
      "object": "episode",
      "id": "6vQ1jWjYcK2mWkQ0dGx3Zp",
      "show_id": "pQ7sHt2Lw9XcV4bN1mRa",
      "title": "Episode 412: Deadline Day Fallout",
      "published_at": "2026-10-14",
      "duration": "1:12:40",
      "duration_seconds": 4360,
      "episode_number": "412",
      "source_platform": "spotify",
      "cover": "https://i.scdn.co/image/ab6765630000ba8a1f0f3c6e2c0b6d1e2f3a4b5c",
      "share_url": "https://open.spotify.com/episode/6vQ1jWjYcK2mWkQ0dGx3Zp"
    }
  },
  "request": null
}

analytics.refreshedAppA show platform's analytics advanced (its last-updated stamp moved forward after a refresh or sync).

Example payload

{
  "object": "event",
  "id": "evt_1a2B3c4D5e6F7g8H9i0JkLmN",
  "type": "analytics.refreshed",
  "api_version": "2026-10-14",
  "created": "2026-10-14T09:30:00Z",
  "workspace_id": "uJm8Fq1kT0bYwZ3xA9cD",
  "source": "app",
  "data": {
    "object": {
      "object": "platform_status",
      "show_id": "pQ7sHt2Lw9XcV4bN1mRa",
      "show_name": "Dugout Daily",
      "platform": "youtube",
      "connected": true,
      "last_updated": "2026-10-14T06:02:31Z",
      "age_hours": 0.4,
      "stale": false
    },
    "previous_attributes": {
      "last_updated": "2026-10-13T06:01:12Z"
    }
  },
  "request": null
}

integration.connectedAPIA platform was connected to a show through the API (by handle, profile URL or API key). The first data refresh may still be running.

Example payload

{
  "object": "event",
  "id": "evt_1a2B3c4D5e6F7g8H9i0JkLmN",
  "type": "integration.connected",
  "api_version": "2026-10-14",
  "created": "2026-10-14T09:30:00Z",
  "workspace_id": "uJm8Fq1kT0bYwZ3xA9cD",
  "source": "api",
  "data": {
    "object": {
      "object": "integration",
      "id": "instagram",
      "show_id": "pQ7sHt2Lw9XcV4bN1mRa",
      "path": "users/pQ7sHt2Lw9XcV4bN1mRa",
      "urls": {
        "app": "https://network.listener.com/app/integrations?show=pQ7sHt2Lw9XcV4bN1mRa",
        "public": null
      },
      "written": {
        "uid": "pQ7sHt2Lw9XcV4bN1mRa",
        "platform": "instagram",
        "handle": "dugoutdaily",
        "url": "https://www.instagram.com/dugoutdaily/"
      },
      "data": {
        "show_id": "pQ7sHt2Lw9XcV4bN1mRa",
        "platform": "instagram",
        "status": "connected",
        "connected": true,
        "username": "dugoutdaily",
        "profile_url": "https://www.instagram.com/dugoutdaily/",
        "refreshed": true,
        "previous_state": "disconnected",
        "previous_account": null
      }
    }
  },
  "request": {
    "id": "req_8f2LkQ0wXv1Tz",
    "idempotency_key": null
  }
}

integration.disconnectedAPIAppA show's platform connection was turned off (through the API or in the app) or lost.

Example payload

{
  "object": "event",
  "id": "evt_1a2B3c4D5e6F7g8H9i0JkLmN",
  "type": "integration.disconnected",
  "api_version": "2026-10-14",
  "created": "2026-10-14T09:30:00Z",
  "workspace_id": "uJm8Fq1kT0bYwZ3xA9cD",
  "source": "app",
  "data": {
    "object": {
      "object": "platform_status",
      "show_id": "pQ7sHt2Lw9XcV4bN1mRa",
      "show_name": "Dugout Daily",
      "platform": "youtube",
      "connected": false,
      "last_updated": "2026-10-14T06:02:31Z",
      "age_hours": 3.1,
      "stale": false
    },
    "previous_attributes": {
      "connected": true
    }
  },
  "request": null
}

integration.staleAppA connected platform has not refreshed for more than 36 hours.

Example payload

{
  "object": "event",
  "id": "evt_1a2B3c4D5e6F7g8H9i0JkLmN",
  "type": "integration.stale",
  "api_version": "2026-10-14",
  "created": "2026-10-14T09:30:00Z",
  "workspace_id": "uJm8Fq1kT0bYwZ3xA9cD",
  "source": "app",
  "data": {
    "object": {
      "object": "platform_status",
      "show_id": "pQ7sHt2Lw9XcV4bN1mRa",
      "show_name": "Dugout Daily",
      "platform": "youtube",
      "connected": true,
      "last_updated": "2026-10-12T20:55:00Z",
      "age_hours": 36.6,
      "stale": true
    },
    "previous_attributes": {
      "stale": false
    }
  },
  "request": null
}

show.updatedAPIA show's or the network's public profile was edited.

Example payload

{
  "object": "event",
  "id": "evt_1a2B3c4D5e6F7g8H9i0JkLmN",
  "type": "show.updated",
  "api_version": "2026-10-14",
  "created": "2026-10-14T09:30:00Z",
  "workspace_id": "uJm8Fq1kT0bYwZ3xA9cD",
  "source": "api",
  "data": {
    "object": {
      "object": "show",
      "id": "pQ7sHt2Lw9XcV4bN1mRa",
      "name": "Dugout Daily",
      "handle": "dugout-daily",
      "image": "https://firebasestorage.googleapis.com/v0/b/listener/o/dugout-daily.jpg",
      "public_url": "https://listener.com/dugout-daily",
      "categories": [
        "Sports",
        "Baseball"
      ]
    }
  },
  "request": {
    "id": "req_8f2LkQ0wXv1Tz",
    "idempotency_key": null
  }
}

Brands & reports

report.createdAPIAppA shared report was published (by hand or by a report automation).

Example payload

{
  "object": "event",
  "id": "evt_1a2B3c4D5e6F7g8H9i0JkLmN",
  "type": "report.created",
  "api_version": "2026-10-14",
  "created": "2026-10-14T09:30:00Z",
  "workspace_id": "uJm8Fq1kT0bYwZ3xA9cD",
  "source": "app",
  "data": {
    "object": {
      "object": "report",
      "id": "rpt_2026_10_weekly_northwind",
      "title": "Weekly network scorecard — Oct 7–13",
      "network_name": "Northwind Audio",
      "time_range": "7d",
      "created_at": "2026-10-14T08:00:12Z",
      "is_automated": true,
      "urls": {
        "network": "https://network.listener.com/report/uJm8Fq1kT0bYwZ3xA9cD/rpt_2026_10_weekly_northwind",
        "public": "https://listener.com/report/uJm8Fq1kT0bYwZ3xA9cD/rpt_2026_10_weekly_northwind"
      }
    }
  },
  "request": null
}

report.deletedAPIAppA shared report was deleted.

Example payload

{
  "object": "event",
  "id": "evt_1a2B3c4D5e6F7g8H9i0JkLmN",
  "type": "report.deleted",
  "api_version": "2026-10-14",
  "created": "2026-10-14T09:30:00Z",
  "workspace_id": "uJm8Fq1kT0bYwZ3xA9cD",
  "source": "app",
  "data": {
    "object": {
      "object": "report",
      "id": "rpt_2026_10_weekly_northwind",
      "deleted": true
    }
  },
  "request": null
}

brand.updatedAPIA brand profile (name, domain, logo, notes, contact) was created or updated.

Example payload

{
  "object": "event",
  "id": "evt_1a2B3c4D5e6F7g8H9i0JkLmN",
  "type": "brand.updated",
  "api_version": "2026-10-14",
  "created": "2026-10-14T09:30:00Z",
  "workspace_id": "uJm8Fq1kT0bYwZ3xA9cD",
  "source": "api",
  "data": {
    "object": {
      "object": "brand",
      "slug": "acme-coffee",
      "name": "Acme Coffee",
      "domain": "acmecoffee.example",
      "logo": "https://cdn.example.com/acme-coffee.png",
      "notes": "Prefers host reads; no competitor mentions in the same episode.",
      "has_contact": true,
      "campaign_count": 4,
      "public_url": "https://network.listener.com/northwind-audio/brands/acme-coffee"
    }
  },
  "request": {
    "id": "req_8f2LkQ0wXv1Tz",
    "idempotency_key": null
  }
}

Webhooks

webhook_endpoint.testOn demand onlyAPISent on demand from the dashboard or POST /v1/webhook-endpoints/{id}/test. Never sent automatically.

Example payload

{
  "object": "event",
  "id": "evt_1a2B3c4D5e6F7g8H9i0JkLmN",
  "type": "webhook_endpoint.test",
  "api_version": "2026-10-14",
  "created": "2026-10-14T09:30:00Z",
  "workspace_id": "uJm8Fq1kT0bYwZ3xA9cD",
  "source": "api",
  "data": {
    "object": {
      "object": "webhook_endpoint_test",
      "endpoint_id": "we_4mT8sKq2Zx7Lb1Nc9VfR3pYd",
      "message": "This is a test event from Listener. Respond with any 2xx status to acknowledge it."
    }
  },
  "request": {
    "id": "req_8f2LkQ0wXv1Tz",
    "idempotency_key": null
  }
}