> For the complete documentation index, see [llms.txt](https://api-reference.usecommune.dev/llms.txt)

# Subscriber joined a form

> POST subscriber.joined_form
> 
> Somebody signed up through one of the newsletter's signup forms and is
> on the list. `data.form_id` and `data.form_name` say which form, and
> `data.page_url` the page it was on, as the reader's browser reported it.
> 
> Two paths land here, and `data.new_subscriber` tells them apart.
> 
> **A new signup** (`new_subscriber: true`). Every form is double opt-in,
> so somebody who was not on the list gets a confirmation email and this
> fires only once they click it. In the same transaction they become a
> subscriber, which publishes `subscriber.created` as well (carrying the
> same `form_id`), and the form's tags are applied, which publishes one
> `subscriber.tagged` per tag. Somebody who had unsubscribed and signs up
> again is this case too: they had to confirm, and `subscriber.created`
> arrives with `resubscribed: true`.
> 
> **Somebody already on the list** (`new_subscriber: false`). They join
> the form straight away with no confirmation email, the form's tags are
> applied, and this is the only subscriber event published, because their
> subscription did not change. This is what lets a form that hands over a
> download reach existing subscribers too.
> 
> Fires every time somebody signs up through a form, including a second
> signup through the same form. An automation that should run once per
> person keeps re-entry off.
> 
> `data.actor` is always null: the reader did this on a page of the
> creator's, and no credential was involved.
> 
> 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.



## Servers
- Production. There is no separate sandbox host.
: https://api.usecommune.com (Production. There is no separate sandbox host.
)



## Parameters
### Headers

- **Commune-Version** (string)
  API version the payload conforms to. Same value as `api_version` in the envelope.

- **Commune-Event-Id** (string(uuid))
  Same value as `id` in the envelope. The dedupe key.

- **Commune-Event-Type** (string)
  Same value as `type` in the envelope. The topic name.

- **Commune-Signature** (string)
  HMAC-SHA256 over `Commune-Timestamp` as Unix seconds, a literal `.`, then the raw request body, keyed by the endpoint's signing secret. Lowercase hex, carried as `v0=` followed by one or more comma separated digests (more than one while a secret is being rotated). The header's timestamp is an RFC 3339 instant, so convert it to Unix seconds before signing. Verify against the raw bytes before parsing the JSON. The webhooks guide has the full procedure.

- **Commune-Timestamp** (string(date-time))
  When this delivery attempt was made, as an RFC 3339 instant in UTC. It differs on every retry, and it IS covered by the signature, in Unix seconds, so a stale or altered one can be rejected. Enforce a tolerance window of a few minutes and dedupe on the event id as well, since a retry inside that window is legitimate.

- **Commune-Delivery-Attempt** (integer)
  1 on the first attempt, incremented on each retry. **Not sent today**: do not rely on it, and be idempotent regardless. The same number is readable after the fact as `attempt` on a `DeliveryAttempt`, so a consumer that needs to tell a retry from a first delivery can ask instead of being told.




### Body: application/json (object)

- **id** (string(uuid))
  Unique id for this event. Stable across redeliveries, so it is the dedupe key. Assigned when the state change is recorded rather than when the message is dispatched.

- **type** (string)
  The topic name, identical to the channel address. Route on this.

- **api_version** (string)
  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))
  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)
  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 topics Commune publishes currently are.

- **actor** (object | null)
  Who caused the change, and `null` when nobody in particular did.

  Populated on a change made through this API's write operations, where it is the credential, and on a change one of the newsletter's own automations made, where it is the run. Null on every other change: an edit a creator made in the product, an import arriving from a provider, a scheduled job, a delivery result reported by the sending provider. Null is therefore the common case and stays a legitimate value. Read it as "this change was attributed", never as "nothing caused this".

  It never names a person: an `api_key` actor is the credential and a `system` actor is an automation run.

  It answers "did this change come in through the API, and under which credential". It is **not** the field to drop the echo of your own write with: use `idempotency_key`, which you chose and therefore already know, whereas `id` here is Commune's own identifier for your credential and no operation reports it back to you. A creator can read that identifier in Commune, but it changes when the credential is replaced, so matching on it puts the loop back silently after a rotation.

- **idempotency_key** (string | null)
  The `Idempotency-Key` of the API write that caused this change, so a consumer can tie an event back to its own request and collapse the duplicates a retried write would otherwise produce.

  **This is how a consumer that writes recognises its own work.** Keep the keys you send, and skip any event carrying one of them. You chose the value, so you know it before the event arrives. `actor` cannot do this job, because Commune's id for your credential is not something this API reports to you.

  Null for every change that did not come in through this API, which is most of them: an edit made in Commune, an import, a scheduled job and a delivery result all have no originating request to key on.

  **It reaches every endpoint registered for the newsletter**, not only the one that made the write, so choose opaque keys such as UUIDs rather than keys carrying your own business identifiers.

- **data** (object)
  Event-specific body. Narrowed by each concrete event schema below.



## 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.



[Powered by Bump.sh](https://bump.sh)
