> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mailchimp Webhook Setup Guide

> Configure Mailchimp to deliver events to StackOne.

## Prerequisites

Before continuing, you should have already completed the following for this connector:

<Steps>
  <Step title="Configure the Connector">
    Enable the connector and set up its connector profile in your project. See <a href="/guides/explore-connectors">Managing Connectors</a>.

    <Columns cols={2}>
      <Card title="Connector Profile" href="/connectors/mailchimp/guides/connector-profile/oauth-2-0" icon="https://stackone-logos.com/api/mailchimp/filled/png" horizontal>
        Mailchimp - OAuth 2.0
      </Card>

      <Card title="Connector Profile" href="/connectors/mailchimp/guides/connector-profile/api-key" icon="https://stackone-logos.com/api/mailchimp/filled/png" horizontal>
        Mailchimp - API Key
      </Card>
    </Columns>
  </Step>

  <Step title="Link an Account">
    Connect an account using <a href="/guides/embedding-stackone-hub">StackOne Hub</a> or <a href="/guides/auth-link">Auth Link</a>.

    <Columns cols={2}>
      <Card title="Link Account" href="/connectors/mailchimp/guides/link-account/oauth-2-0" icon="https://stackone-logos.com/api/mailchimp/filled/png" horizontal>
        Mailchimp - OAuth 2.0
      </Card>

      <Card title="Link Account" href="/connectors/mailchimp/guides/link-account/api-key" icon="https://stackone-logos.com/api/mailchimp/filled/png" horizontal>
        Mailchimp - API Key
      </Card>
    </Columns>
  </Step>
</Steps>

<section data-guide-section data-guide-scopes="">
  <h2>Subscribe via the StackOne dashboard</h2>

  <p>This connector uses <strong>Programmatic Webhooks</strong>. When you enable webhook events for a connected Mailchimp account, StackOne automatically registers a webhook on each configured audience (via `POST /lists/{list_id}/webhooks`), subscribed to all audience events from all sources (user, admin, and API).</p>

  <Steps>
    <Step title="Set the Webhook Audience ID">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>In the connection's configuration, set <strong>Webhook Audience ID</strong> to the ID of the Mailchimp audience you want events from — or several as comma-separated IDs (e.g. `a6b5da1054` or `a6b5da1054,f7c8eb2165`). A webhook is registered on each audience.</p>

        <ul>
          <li>Find audience IDs in Mailchimp under <strong>Audience</strong> → <strong>Settings</strong> → <strong>Audience name and defaults</strong> (the *Audience ID* field), or by calling the connector's `list_audiences` action.</li>
          <li>Enter the IDs without spaces around the commas.</li>
        </ul>
      </div>
    </Step>

    <Step title="Select event subscriptions in the dashboard">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>In the StackOne dashboard, open the Mailchimp connector profile and enable the webhook events you want delivered downstream. See the <strong>Available Webhook Events</strong> section below for the full list.</p>
      </div>
    </Step>

    <Step title="Connect the Mailchimp account">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>On account connection (or when event subscriptions change), StackOne registers a webhook on each configured audience on your behalf using the connected account's credentials. Mailchimp verifies the endpoint when each webhook is created; StackOne answers the verification automatically.</p>
      </div>
    </Step>

    <Step title="Verify delivery">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Trigger a matching change in Mailchimp (for example, subscribe a test contact to the audience) and confirm the event reaches your downstream consumer.</p>

        <ul>
          <li>Mailchimp sends events as form-encoded HTTP POSTs; StackOne responds with `200 OK` automatically.</li>
          <li>If the endpoint is unavailable or takes more than 10 seconds to respond, Mailchimp retries at increasing intervals over 75 minutes, and may disable webhooks that keep failing.</li>
        </ul>
      </div>
    </Step>

    <Step title="Receive events from additional audiences">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>To receive events from more audiences, append their IDs to the <strong>Webhook Audience ID</strong> field (comma-separated). Avoid editing the field while webhooks are registered — the stored registration is paired with the audience list at creation time, so unsubscribe first, update the IDs, then re-subscribe. Webhooks orphaned by an out-of-sync edit can be removed in Mailchimp under <strong>Audience</strong> → <strong>Audience settings</strong> → <strong>Manage webhooks</strong>.</p>
      </div>
    </Step>

    <Step title="Unsubscribe">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Changing your event selection re-registers the StackOne-managed webhooks. Disconnecting the account deletes them from every configured audience, stopping deliveries.</p>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available Webhook Events</h2>

  <p>The following Mailchimp audience events can be enabled. The StackOne-managed webhooks are subscribed to all six event types in Mailchimp; only events enabled in StackOne are delivered downstream.</p>

  <Steps>
    <Step title="Contact events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to contacts on the audience.</p>

        <ul>
          <li><strong>Email Subscribed</strong> (`subscribe`) — Fired when a contact subscribes to the audience</li>
          <li><strong>Email Unsubscribed</strong> (`unsubscribe`) — Fired when a contact unsubscribes or is removed</li>
          <li><strong>Profile Updated</strong> (`profile`) — Fired when a subscriber's profile is updated</li>
          <li><strong>Email Address Changed</strong> (`upemail`) — Fired when a subscriber changes their email address</li>
          <li><strong>Email Cleaned</strong> (`cleaned`) — Fired when an address is cleaned from the audience (hard bounce or abuse complaint)</li>
        </ul>
      </div>
    </Step>

    <Step title="Campaign events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to campaign sending.</p>

        <ul>
          <li><strong>Campaign Sent</strong> (`campaign`) — Fired when a campaign to the audience finishes sending or is cancelled</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Delivery format</h2>

  <p>Details of how Mailchimp delivers events to StackOne.</p>

  <Steps>
    <Step title="Form-encoded payloads">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Mailchimp delivers each event as an HTTP POST with an `application/x-www-form-urlencoded` body — a `type` field, a `fired_at` timestamp, and the event details under `data`.</p>
      </div>
    </Step>
  </Steps>
</section>

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.