List the events you can subscribe to

Overview

See every event type we can send, with a description of each.

Use this before creating a subscription, to decide what you want. Events with default_kind immediate can be picked one by one on an immediate subscription. Events with default_kind batch can't be picked: a batch subscription receives them all as one cache_invalidation ping per location per interval (delivered_as shows the name that reaches your endpoint).

You'll need a partner token.

Returns the event catalogue and the allowed batch intervals.

For when each event is sent and a sample payload of each, see the Webhook event catalogue.

Prerequisites

A Partner bearer token. See Authentication.

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

GET /api/v1/partner/webhooks/events

Authentication

Partner token

Only partner users can call it; other tokens get 403.
The catalogue is for your partner: events that apply only to a specific partner are listed only for that partner.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

None.

Request payload

None.

Response body

The payload is inside data.

Field	Type	Description
`data`	array of objects	One entry per event.
`data[].value`	string	The event name, e.g. `review_pull_connected`. Use it in `events` when you create or update an immediate subscription.
`data[].category`	string	`ingest`, `flag`, `response`, `connection`, `usage` or `billing`.
`data[].description`	string	When the event fires.
`data[].default_kind`	string	`immediate` or `batch`: the subscription type that receives it.
`data[].delivered_as`	string	The event name that arrives on your endpoint: the event's own name for `immediate` events, always `cache_invalidation` for `batch` events.
`meta`	object	Extra details.
`meta.batch_interval_hours_options`	array of integers	The allowed `batch_interval_hours`: `[1, 2, 4, 6, 12]`.

Response payload

{
  "data": {
    "data": [
      {
        "value": "review_ingested",
        "category": "ingest",
        "description": "A new partner-specific review was ingested via the partner API, hosted form, or import. Only fires for partner-specific reviews; edits arrive as review_updated.",
        "default_kind": "batch",
        "delivered_as": "cache_invalidation"
      },
      {
        "value": "review_pulled_from_platform",
        "category": "ingest",
        "description": "A new review was pulled from a connected review site (Google, Facebook, Caring, or any ReviewData-routed site). Fires for every partner.",
        "default_kind": "batch",
        "delivered_as": "cache_invalidation"
      },
      {
        "value": "review_campaign_collected",
        "category": "ingest",
        "description": "A review was collected through a solicitation campaign flow.",
        "default_kind": "batch",
        "delivered_as": "cache_invalidation"
      },
      {
        "value": "review_updated",
        "category": "ingest",
        "description": "An existing review’s rating or content changed, on any review site (partner-specific included).",
        "default_kind": "batch",
        "delivered_as": "cache_invalidation"
      },
      {
        "value": "review_deleted",
        "category": "ingest",
        "description": "A review was removed. Universal across every source — partner-admin moderation, a Google location switch, a Facebook object-gone response, or any other site. Always a soft delete, so the row and its history remain.",
        "default_kind": "immediate",
        "delivered_as": "review_deleted"
      },
      {
        "value": "platform_removal_detected",
        "category": "ingest",
        "description": "A backward scrape detected the review is no longer present on the source platform.",
        "default_kind": "immediate",
        "delivered_as": "platform_removal_detected"
      },
      {
        "value": "profanity_detected",
        "category": "ingest",
        "description": "A profanity scan matched the review body (logged only on hit, content auto-redacted).",
        "default_kind": "immediate",
        "delivered_as": "profanity_detected"
      },
      {
        "value": "flag_submitted",
        "category": "flag",
        "description": "A removal request (flag) was raised on a review; flag_status is now pending.",
        "default_kind": "immediate",
        "delivered_as": "flag_submitted"
      },
      {
        "value": "flag_denied",
        "category": "flag",
        "description": "The removal request was declined and the review stays visible; flag_status is now denied.",
        "default_kind": "immediate",
        "delivered_as": "flag_denied"
      },
      {
        "value": "flag_approved_removed",
        "category": "flag",
        "description": "The review was removed following the removal request; flag_status is now approved_removed.",
        "default_kind": "immediate",
        "delivered_as": "flag_approved_removed"
      },
      {
        "value": "flag_submitted_to_platform",
        "category": "flag",
        "description": "The removal request was sent to the source platform; flag_status is now submitted_to_platform.",
        "default_kind": "immediate",
        "delivered_as": "flag_submitted_to_platform"
      },
      {
        "value": "response_drafted",
        "category": "response",
        "description": "A response draft was created on a review.",
        "default_kind": "immediate",
        "delivered_as": "response_drafted"
      },
      {
        "value": "response_updated",
        "category": "response",
        "description": "A response’s content was edited, or a newer reply to an existing response was received from the source platform.",
        "default_kind": "immediate",
        "delivered_as": "response_updated"
      },
      {
        "value": "response_received",
        "category": "response",
        "description": "A reply was received from the source platform for an existing review that had no response.",
        "default_kind": "immediate",
        "delivered_as": "response_received"
      },
      {
        "value": "response_deleted",
        "category": "response",
        "description": "A response was removed (soft or hard delete).",
        "default_kind": "immediate",
        "delivered_as": "response_deleted"
      },
      {
        "value": "ai_response_generated",
        "category": "response",
        "description": "An AI-suggested response was drafted for the review.",
        "default_kind": "immediate",
        "delivered_as": "ai_response_generated"
      },
      {
        "value": "response_submitted_to_platform",
        "category": "response",
        "description": "A response was dispatched to the source platform (Google / Facebook / Caring).",
        "default_kind": "immediate",
        "delivered_as": "response_submitted_to_platform"
      },
      {
        "value": "response_post_succeeded",
        "category": "response",
        "description": "The source platform accepted and published the response.",
        "default_kind": "immediate",
        "delivered_as": "response_post_succeeded"
      },
      {
        "value": "response_post_failed",
        "category": "response",
        "description": "The source platform rejected the response (reason in metadata).",
        "default_kind": "immediate",
        "delivered_as": "response_post_failed"
      },
      {
        "value": "response_status_changed",
        "category": "response",
        "description": "A response moved between lifecycle statuses (draft → submitted → posted / failed).",
        "default_kind": "immediate",
        "delivered_as": "response_status_changed"
      },
      {
        "value": "response_resubmitted",
        "category": "response",
        "description": "A previously failed response was re-fired to the source platform.",
        "default_kind": "immediate",
        "delivered_as": "response_resubmitted"
      },
      {
        "value": "review_pull_connected",
        "category": "connection",
        "description": "Review pulling (scraping) for a location's review site started or resumed.",
        "default_kind": "immediate",
        "delivered_as": "review_pull_connected"
      },
      {
        "value": "review_pull_disconnected",
        "category": "connection",
        "description": "Review pulling (scraping) for a location's review site is unavailable — connection lost, no URL configured, or paused (reason + error_code carry which).",
        "default_kind": "immediate",
        "delivered_as": "review_pull_disconnected"
      },
      {
        "value": "response_post_connected",
        "category": "connection",
        "description": "Response posting for a location's review site became active.",
        "default_kind": "immediate",
        "delivered_as": "response_post_connected"
      },
      {
        "value": "response_post_disconnected",
        "category": "connection",
        "description": "Response posting for a location's review site is unavailable — disconnected, awaiting approval, or no URL configured.",
        "default_kind": "immediate",
        "delivered_as": "response_post_disconnected"
      },
      {
        "value": "usage.threshold_warning",
        "category": "usage",
        "description": "A location crossed a usage warning threshold (75% / 80%) for a metered plan feature this period.",
        "default_kind": "immediate",
        "delivered_as": "usage.threshold_warning"
      },
      {
        "value": "usage.limit_reached",
        "category": "usage",
        "description": "A location reached 100% of its included units for a metered plan feature this period.",
        "default_kind": "immediate",
        "delivered_as": "usage.limit_reached"
      },
      {
        "value": "plan.cancelled",
        "category": "billing",
        "description": "A location cancelled its subscription and will no longer be billed.",
        "default_kind": "immediate",
        "delivered_as": "plan.cancelled"
      },
      {
        "value": "brand_plan.cancelled",
        "category": "billing",
        "description": "A brand (or partner) cancelled its subscription across its locations.",
        "default_kind": "immediate",
        "delivered_as": "brand_plan.cancelled"
      },
      {
        "value": "plan.changed",
        "category": "billing",
        "description": "A location or brand subscription plan was changed (upgrade, downgrade or proration).",
        "default_kind": "immediate",
        "delivered_as": "plan.changed"
      }
    ],
    "meta": {
      "batch_interval_hours_options": [
        1,
        2,
        4,
        6,
        12
      ]
    }
  }
}

Examples

Success payload

See Response payload.

Error payload

401 Missing or invalid token

{
  "message": "Unauthenticated."
}

403 Not a Partner token

{
  "message": "Only partner-admin users can manage webhook subscriptions.",
  "status": "error",
  "errors": []
}

500 Server error

{
  "message": "Server Error"
}

Status	Meaning
`200`	The event catalogue.
`401`	The token is missing, expired or invalid.
`403`	The token isn't a Partner token.
`500`	Unexpected server error.

Example request

curl --request GET \
  --url "https://production-api.shoutaboutus.com/api/v1/partner/webhooks/events" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'