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

# WhatsApp Business Webhook Setup Guide

> Configure WhatsApp Business to deliver events to StackOne.

## Prerequisites

The connector should already be set up, with a Connector Profile and a Linked Account. See [Getting Started](/connectors/whatsapp-business#getting-started) on the WhatsApp Business connector page.

<section data-guide-section data-guide-scopes="">
  <h2>Prepare StackOne</h2>

  <p>Enable the WhatsApp Business events you want on the connector in StackOne, including <strong>Webhook Verification</strong>, which answers Meta's verification request when you save the callback URL.</p>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Connect the account</h2>

  <p>Connect the WhatsApp Business account in StackOne with its WhatsApp Business Account ID. When events are enabled, StackOne subscribes your Meta app to that WhatsApp Business Account automatically and unsubscribes it when the account is disconnected.</p>

  <Steps>
    <Step title="Copy the Native Webhook URL">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Copy the <strong>Native Webhook URL</strong> shown on the WhatsApp Business Linked Account in StackOne. It identifies that account, so every webhook Meta sends to it is routed to the account.</p>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Configure the webhook in WhatsApp</h2>

  <p>Set the callback URL and webhook fields in your Meta app after you connect the account in StackOne. The Cloud API has no endpoint for this step, so it is done in the App Dashboard.</p>

  <Steps>
    <Step title="Open the webhook settings">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>In your app on <a href="https://developers.facebook.com/apps" target="_blank" rel="noopener noreferrer">Meta for Developers</a>, open <strong>Use cases</strong>, customize <strong>Connect on WhatsApp</strong>, and select <strong>Step 2. Production setup</strong>. Expand <strong>Configure Webhooks</strong>.</p>

        <img src="https://mintcdn.com/stackone-60/4OonqPZsXrAh6dgg/connectors/whatsapp-business/images/events-open-webhooks.png?fit=max&auto=format&n=4OonqPZsXrAh6dgg&q=85&s=119406e5691d2da664ad1d99a0958337" alt="The Step 2 Production setup page with the menu item and the Configure Webhooks section highlighted" width="1280" height="800" data-path="connectors/whatsapp-business/images/events-open-webhooks.png" />
      </div>
    </Step>

    <Step title="Set the callback URL">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Paste the Native Webhook URL into <strong>Callback URL</strong>, enter any value in <strong>Verify token</strong>, and click <strong>Verify and save</strong>. Meta sends a verification request to the URL and StackOne answers it.</p>

        <ul>
          <li>If verification fails, check that the <strong>Webhook Verification</strong> event is enabled in StackOne and the URL was copied in full.</li>
          <li>While the app is unpublished, Meta only delivers test webhooks sent from the App Dashboard. To receive real messages and status updates for numbers other than the test number, publish the app with <strong>Publish your app</strong>.</li>
        </ul>

        <img src="https://mintcdn.com/stackone-60/4OonqPZsXrAh6dgg/connectors/whatsapp-business/images/events-callback-url.png?fit=max&auto=format&n=4OonqPZsXrAh6dgg&q=85&s=b16071b5a1ae44061e8272be38910137" alt="The Configure Webhooks section with the Callback URL and Verify token fields and the Verify and save button highlighted" width="1280" height="800" data-path="connectors/whatsapp-business/images/events-callback-url.png" />
      </div>
    </Step>

    <Step title="Subscribe to the webhook fields">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Under <strong>Webhook fields</strong>, turn on <strong>Subscribe</strong> for every field whose events you enabled in StackOne, so the toggle shows <strong>Subscribed</strong>.</p>

        <img src="https://mintcdn.com/stackone-60/4OonqPZsXrAh6dgg/connectors/whatsapp-business/images/events-webhook-fields.png?fit=max&auto=format&n=4OonqPZsXrAh6dgg&q=85&s=f712bc5b3777bd9115a6e23f1b15d23d" alt="The Webhook fields table with the account_alerts, account_review_update, and account_update fields subscribed and highlighted" width="1280" height="800" data-path="connectors/whatsapp-business/images/events-webhook-fields.png" />
      </div>
    </Step>

    <Step title="Subscribe to the messages field">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Make sure <strong>messages</strong> shows <strong>Subscribed</strong>. This field delivers both incoming messages and the status updates of messages you send.</p>

        <ul>
          <li>Click <strong>Test</strong> next to a subscribed field under <strong>Webhook fields</strong> to send a sample webhook. It should arrive as an event on the account in StackOne. The sample uses placeholder IDs and content, so send a real WhatsApp message to the business number to check real data.</li>
        </ul>

        <img src="https://mintcdn.com/stackone-60/4OonqPZsXrAh6dgg/connectors/whatsapp-business/images/events-messages-field.png?fit=max&auto=format&n=4OonqPZsXrAh6dgg&q=85&s=b41253fd898d90cb1d0ffe304aae46ae" alt="The Webhook fields table with the messages field, its Test link, and its Subscribed toggle highlighted" width="1280" height="800" data-path="connectors/whatsapp-business/images/events-messages-field.png" />
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available webhook events</h2>

  <p>The following WhatsApp Business events can be enabled. Only events enabled in StackOne are delivered, and Meta only sends events for webhook fields subscribed in the App Dashboard.</p>

  <Steps>
    <Step title="Verification and health checks (required)">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Enable these whenever any other event is enabled.</p>

        <ul>
          <li><strong>Webhook Verification</strong> (`webhook_verification`) — Answers Meta's verification request with the challenge value when the callback URL is saved. Without it, Meta rejects the callback URL</li>
          <li><strong>Active Check</strong> (`active_check`) — Acknowledges deliveries that carry no WhatsApp Business Account entries, so Meta does not retry them</li>
        </ul>
      </div>
    </Step>

    <Step title="Message events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events from the `messages` webhook field.</p>

        <ul>
          <li><strong>Message Received</strong> (`message.received`) — Fired when a WhatsApp user sends a message to a business phone number, including text, media, location, contacts, reactions, and interactive replies</li>
          <li><strong>Message Status Updated</strong> (`message.status_updated`) — Fired when a message sent from a business phone number is sent, delivered, read, or fails</li>
        </ul>
      </div>
    </Step>

    <Step title="Template events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events from the `message_template_status_update` and `message_template_quality_update` webhook fields.</p>

        <ul>
          <li><strong>Template Status Updated</strong> (`template.status_updated`) — Fired when a message template is approved, rejected, paused, disabled, or otherwise changes review status</li>
          <li><strong>Template Quality Updated</strong> (`template.quality_updated`) — Fired when a message template's quality rating changes</li>
        </ul>
      </div>
    </Step>

    <Step title="Phone number events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events from the `phone_number_quality_update` webhook field.</p>

        <ul>
          <li><strong>Phone Number Quality Updated</strong> (`phone_number.quality_updated`) — Fired when a business phone number's messaging limit or throughput changes</li>
        </ul>
      </div>
    </Step>

    <Step title="Account events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events from the `account_update`, `account_review_update`, and `account_alerts` webhook fields.</p>

        <ul>
          <li><strong>Account Updated</strong> (`account.updated`) — Fired when a WhatsApp Business Account changes, such as a restriction, policy violation, verification change, or deletion</li>
          <li><strong>Account Review Updated</strong> (`account.review_updated`) — Fired when the review of a WhatsApp Business Account is completed</li>
          <li><strong>Account Alert</strong> (`account.alert`) — Fired when Meta raises an alert about a WhatsApp Business Account, business, or phone number, such as a messaging limit or capability change</li>
        </ul>
      </div>
    </Step>

    <Step title="Contact events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events from the `user_preferences` webhook field.</p>

        <ul>
          <li><strong>User Preferences Updated</strong> (`user.preferences_updated`) — Fired when a WhatsApp user stops or resumes marketing messages from the business</li>
        </ul>
      </div>
    </Step>

    <Step title="Group events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events from the `group_lifecycle_update`, `group_participants_update`, and `group_settings_update` webhook fields. Requires a business phone number that is eligible for groups.</p>

        <ul>
          <li><strong>Group Lifecycle Updated</strong> (`group.lifecycle_updated`) — Fired when a group is created or deleted</li>
          <li><strong>Group Participants Updated</strong> (`group.participants_updated`) — Fired when participants join or leave a group, or a join request is created or resolved</li>
          <li><strong>Group Settings Updated</strong> (`group.settings_updated`) — Fired when a group's subject, description, or profile picture update completes</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

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

  <p>Details of how Meta delivers WhatsApp webhooks to StackOne.</p>

  <Steps>
    <Step title="Batched payloads">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Each request holds an `entry` array, one item per WhatsApp Business Account, and each entry holds a `changes` array with the webhook `field` and its `value`. StackOne emits one event per change.</p>

        <ul>
          <li>Incoming messages are in `value.messages` and status updates in `value.statuses`, both under the `messages` field.</li>
          <li>Timestamps are unix seconds; StackOne converts them to ISO 8601 for the event date.</li>
        </ul>
      </div>
    </Step>

    <Step title="Retries and duplicates">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Meta retries deliveries that do not receive a 200 response for up to 7 days and may deliver a webhook more than once. Deduplicate messages on the WhatsApp message ID.</p>
      </div>
    </Step>

    <Step title="Signature">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Meta signs each delivery with the `X-Hub-Signature-256` header, an HMAC-SHA256 of the request body keyed with the App Secret.</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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.