Subscriber tag added or removed | REST API documentation

Subscriber tag added or removed Webhook

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL


        
          
            https://api-reference.usecommune.dev/mcp

Standard setup for AI tools providing an mcp.json file

{
  "REST API MCP server": {
    "url": "https://api-reference.usecommune.dev/mcp"
  }
}

POST https://webhook.example.com

Webhook signature

A tag was added to or taken off a subscriber. data.direction says which: assigned when the tag was put on, removed when it was taken off.

One topic for both directions on purpose. Membership of a segment changing is a single concept, and a consumer mirroring an audience wants every change to it, so splitting the directions would only make them subscribe twice to hear the whole story.

Applying a tag is idempotent, so re-applying one the subscriber already has does not produce a second event. Tags matter beyond bookkeeping: they scope who an article is sent to and who can see it, so treat these as segment membership changes rather than as labels.

Deleting the tag itself is a soft delete and is a different, unmodelled change: it retires the tag for everyone at once rather than removing one assignment, so it does not fan out into one event per subscriber here.

Delivered as a single HTTPS POST to the consumer's registered endpoint, with the message as the JSON request body. Respond 2xx to acknowledge. Anything else, or a timeout, is retried with backoff, so acknowledge fast and do the work afterwards.

Headers

Commune-Version string Required

API version the payload conforms to. Same value as api_version in the envelope.
Commune-Event-Id string(uuid) Required

Same value as id in the envelope. The dedupe key.
Commune-Event-Type string Required

Same value as type in the envelope. The topic name.
Commune-Signature string Required

HMAC over the raw request body. Verify before parsing.
Commune-Timestamp string Required

Unix seconds the signature was produced at. Reject anything outside your tolerance window.
Commune-Delivery-Attempt integer

1 on the first attempt, incremented on each retry. Informational only. A consumer must be idempotent regardless of its value.

Minimum value is 1.

application/json

Body Required

A subscriber tag was applied or taken off.

id string(uuid) Required

Unique id for this event. Stable across redeliveries, so it is the dedupe key. It is the primary key of the row the publisher wrote, which means it is assigned when the state change is recorded, not when the message is dispatched.
type string Required

The topic name, identical to the channel address. Route on this.

Value is subscriber.tagged.
api_version string Required

The Commune-Version value this payload conforms to. Present on the message itself, not only on the request header, so an event persisted to a consumer's own store stays self-describing.
occurred_at string(date-time) Required

RFC 3339 timestamp of the state change, not of the delivery attempt. Use it to order events, since delivery order is not guaranteed.
newsletter_id string(uuid) | null Required

The newsletter the change belongs to. This is the tenant boundary: a consumer only ever receives events for newsletters its credential can read. Null only for events that are genuinely not newsletter-scoped, which none of the 21 topics currently are.
actor object | null Required

Who caused the change. ALWAYS null today and consumers must treat it that way: the public API is currently read-only, so nothing that reaches this catalog was triggered through it, and Commune does not backfill an actor for changes made in the product UI or by a cron. The field exists now so that populating it, once writes exist, is an additive change rather than a new envelope version.

Additional properties are NOT allowed.
Hide actor attributes Show actor attributes object | null
- type string Required
  
  user for a change a person made through an authenticated session, api_key for a public API write, system for a cron or webhook ingest with no human behind it.
  
  Values are user, api_key, or system.
- id string Required
  
  Identifier of the actor within its type. A user id for user, a key id (never the secret) for api_key, a stable job name for system.
- label string | null
  
  Human-readable name for display. Best effort, may be null.
idempotency_key string | null Required

ALWAYS null today. Once the public API accepts writes this carries the Idempotency-Key header of the write that caused the change, so a consumer can tie an event back to its own request and collapse the duplicates a retried write would otherwise produce. Null stays a legitimate value even then: a change made in the product UI or by a cron has no originating request to key on.

Maximum length is 255.
data object Required

Event-specific body. Narrowed by each concrete event schema below.
Hide data attributes Show data attributes object
- subscriber_id string(uuid) Required
- email string(email)
- tag_id string(uuid) Required
- tag_name string Required
  
  The tag's name at the time of the change.
- direction string Required
  
  Whether the subscriber joined the segment or left it. Branch on this: it is the only thing that differs between the two changes this topic carries.
  
  Values are assigned or removed.

Responses

200

The consumer accepted the delivery. Any 2xx acknowledges the message and it is not sent again.
4XX

The consumer rejected the delivery. Handled exactly like a 5xx: the message is retried with backoff, because a rejection cannot be told apart from a consumer that is briefly misconfigured.
5XX

The consumer failed to handle the delivery. Retried with backoff. A timeout is the same case and is retried too.

POST subscriber.tagged

Request examples

{
  "id": "018f2a91-bbbb-7000-8000-00000000000b",
  "type": "subscriber.tagged",
  "api_version": "2026-08-26",
  "occurred_at": "2026-08-26T14:00:00Z",
  "newsletter_id": "7d3f1c02-58a1-4a4e-9a0b-2f6d1c9e4411",
  "actor": null,
  "idempotency_key": null,
  "data": {
    "subscriber_id": "33445566-7788-4990-a1b2-c3d4e5f60718",
    "email": "reader@example.com",
    "tag_id": "aa11bb22-cc33-4d44-8e55-ff6677889900",
    "tag_name": "Founding member",
    "direction": "assigned"
  }
}

{
  "id": "018f2a91-cccc-7000-8000-00000000000c",
  "type": "subscriber.tagged",
  "api_version": "2026-08-26",
  "occurred_at": "2026-08-26T14:05:00Z",
  "newsletter_id": "7d3f1c02-58a1-4a4e-9a0b-2f6d1c9e4411",
  "actor": null,
  "idempotency_key": null,
  "data": {
    "subscriber_id": "33445566-7788-4990-a1b2-c3d4e5f60718",
    "email": "reader@example.com",
    "tag_id": "aa11bb22-cc33-4d44-8e55-ff6677889900",
    "tag_name": "Founding member",
    "direction": "removed"
  }
}