Subscriber joined a form 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

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

Close
POST https://webhook.example.com

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.

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-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) Required

    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.

    Minimum value is 1.

application/json

Body Required

Somebody signed up through one of the newsletter's forms and is on the list.

  • id string(uuid) Required

    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 Required

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

    Value is subscriber.joined_form.

  • 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 topics Commune publishes currently are.

  • actor object | null Required

    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.

    Additional properties are NOT allowed.

    Hide actor attributes Show actor attributes object | null
    • type string Required

      api_key for a change made through this API. system for a change one of the newsletter's own automations made, where id is the automation run and label names the automation: see automation.run.started for what that attribution is for. user is reserved for a change a named person made through an authenticated session and is not emitted.

      An OAuth access token reports as api_key as well. The two credentials are interchangeable everywhere else in this API, and a separate value here would be a distinction a consumer cannot act on.

      Values are user, api_key, or system.

    • id string Required

      Identifier of the actor within its type. For api_key it is the credential's own id and never its secret, and it is the same value that appears in a creator's list of credentials, so an event can be traced back to the integration that caused it.

    • label string | null

      Human-readable name for display. Best effort, may be null.

  • idempotency_key string | null Required

    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.

    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) Required
    • form_id string(uuid) Required
    • form_name string Required

      The form's name at the time of the signup. Only the creator sees it; readers see the form's heading.

    • new_subscriber boolean Required

      True when the signup put them on the list: they were not on it, or had unsubscribed, and confirmed by email. False when they were already subscribed and joined the form straight away, with no confirmation email and no subscriber.created.

    • page_url string | null Required

      The page the form was on, as the reader's browser reported it. Null when the browser sent none, which is the usual case for the hosted form page. Not verified: a signup can name any page.

    • joined_at string(date-time) Required

      When they joined the form. For a new subscriber this is when they confirmed, not when they first submitted the form.

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.joined_form
Request examples
{
  "id": "018f2a90-aaaa-7000-8000-00000000001a",
  "type": "subscriber.joined_form",
  "api_version": "2026-08-26",
  "occurred_at": "2026-11-15T10:42: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",
    "form_id": "5b7e2c10-3d4f-4a5b-8c6d-7e8f9a0b1c2d",
    "form_name": "Checklist download",
    "new_subscriber": true,
    "page_url": "https://example.com/blog/the-checklist",
    "joined_at": "2026-11-15T10:42:00Z"
  }
}
{
  "id": "018f2a90-bbbb-7000-8000-00000000001b",
  "type": "subscriber.joined_form",
  "api_version": "2026-08-26",
  "occurred_at": "2026-11-15T11:05:12Z",
  "newsletter_id": "7d3f1c02-58a1-4a4e-9a0b-2f6d1c9e4411",
  "actor": null,
  "idempotency_key": null,
  "data": {
    "subscriber_id": "44556677-8899-4aa1-b2c3-d4e5f6071829",
    "email": "longtime@example.com",
    "form_id": "5b7e2c10-3d4f-4a5b-8c6d-7e8f9a0b1c2d",
    "form_name": "Checklist download",
    "new_subscriber": false,
    "page_url": null,
    "joined_at": "2026-11-15T11:05:12Z"
  }
}