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

# Webhook Settings

> Forward Meta WhatsApp webhook events to your own URL, and understand how this differs from Xobito's outbound CRUD webhooks.

Xobito has **two separate webhook systems**. They share the word "webhook" but do very different things — pick the right one for the job.

* **Flow A — Outbound CRUD webhooks.** Xobito fires events when contacts, statuses, or sources are created, updated, or deleted in your workspace. Configured under **Settings → Webhook Settings** (the CRUD section). Documented at [Webhooks Overview](/developers/webhooks-overview).
* **Flow B — Meta webhook forwarder.** Xobito receives every WhatsApp webhook Meta sends to your WABA (account alerts, message echoes, quality ratings, etc.) and can **forward** the ones you care about to your own URL. Configured under **Settings → Webhook Settings** in the "Webhook Resend" section.

This page documents both, focuses on Flow B (which has no standalone page until now), and helps you pick the right tool.

## The two flows at a glance

|                    | **Flow A — Outbound CRUD**                         | **Flow B — Meta forwarder**                                                      |
| ------------------ | -------------------------------------------------- | -------------------------------------------------------------------------------- |
| Source of events   | Your Xobito workspace                              | Meta (WhatsApp Cloud API)                                                        |
| Events available   | Contact, Status, Source — create/update/delete     | 30+ Meta webhook fields (messages, calls, flows, quality, account updates, etc.) |
| Signed?            | Yes — HMAC-SHA256                                  | **No signature** — see [security note](#security-of-forwarded-events)            |
| Retries on failure | 3 attempts, 1s / 2s backoff between retries        | None documented                                                                  |
| Timeout            | 30s                                                | Relies on Meta's delivery to Xobito                                              |
| Typical use        | Sync your CRM when a contact is edited in Xobito   | Mirror Meta events to an automation platform, data lake, or CRM                  |
| Docs               | [Webhooks Overview](/developers/webhooks-overview) | This page                                                                        |

## When to use Flow A vs Flow B

<CardGroup cols={2}>
  <Card title="Use Flow A when..." icon="arrow-right-from-bracket">
    You edit records *inside Xobito* and want another system to learn about the change — for example, update a HubSpot contact when an agent edits the Xobito contact record.
  </Card>

  <Card title="Use Flow B when..." icon="message-bot">
    You want a copy of raw WhatsApp webhook events from Meta — for example, pipe incoming customer messages into an n8n workflow, or record template quality changes in your data warehouse.
  </Card>
</CardGroup>

<Note>
  Flows are independent. You can enable neither, one, or both.
</Note>

## Flow B — Meta webhook forwarder

Meta sends your WABA all kinds of webhook events: incoming messages, delivery status, template approval updates, phone-number quality changes, flow events, and more. Xobito receives and processes them so the dashboard, campaigns, and bots work correctly.

The **Webhook Resend** feature does one extra thing: for the event fields **you tick**, Xobito also re-posts the payload to a URL **you choose**, so your own systems get a copy.

### Enable forwarding

<Steps>
  <Step title="Open Settings → Webhook Settings">
    Sidebar → **Settings** → **Webhook Settings**.
  </Step>

  <Step title="Turn on 'Enable Webhook Resend'">
    Flip the master toggle. Until this is on, nothing is forwarded.
  </Step>

  <Step title="Enter your destination URL">
    Paste the full HTTPS URL of the endpoint that should receive the events.
  </Step>

  <Step title="Set a method label (required)">
    Free-text label used to describe the request style to your operator (e.g. `POST`, `POST-JSON`, `Zapier-hook`). This is a note, not a validated HTTP verb — Xobito does not change how it calls your endpoint based on this value. **Required whenever Enable Webhook Resend is on.**
  </Step>

  <Step title="Select which Meta fields to forward">
    Tick the boxes next to the event fields you care about. Leave the rest unticked to avoid noise.
  </Step>

  <Step title="Save">
    Changes take effect immediately. The next matching Meta event will be re-posted to your URL.
  </Step>
</Steps>

### Field reference

<ParamField path="enable_webhook_resend" type="boolean" default="false">
  Master on/off switch. When `false`, no events are forwarded regardless of which fields are ticked.
</ParamField>

<ParamField path="whatsapp_data_resend_to" type="string" required>
  Destination URL that receives the forwarded payload. Must be a valid URL (Laravel `url` validator), max 255 characters. Required when `enable_webhook_resend` is `true`. Use HTTPS in production.
</ParamField>

<ParamField path="webhook_resend_method" type="string" required>
  Free-text label (max 255 chars). Stored as-is in workspace settings — useful for documenting *how* your endpoint expects the request, or which integration it belongs to. Does **not** change Xobito's delivery behaviour. Required when `enable_webhook_resend` is `true` (validation rule `required_if:enable_webhook_resend,true`).
</ParamField>

<ParamField path="webhook_selected_fields" type="array">
  JSON array of Meta webhook field slugs to forward — see the [full list below](#meta-fields-you-can-forward). Only ticked fields are forwarded; everything else Xobito receives from Meta is handled internally and not re-posted.
</ParamField>

<Note>
  All input is sanitised via Xobito's `PurifiedInput` rule (strips control characters, normalises whitespace). Very long labels or URLs are rejected at 255 characters.
</Note>

### Security of forwarded events

<Warning>
  **Forwarded payloads are not signed by Xobito.** Unlike Flow A (outbound CRUD webhooks), there is no HMAC-SHA256 signature on Flow B. Your endpoint cannot cryptographically verify that a request came from Xobito.
</Warning>

Because forwards are unsigned, treat your receiver conservatively:

* **Always use HTTPS** for `whatsapp_data_resend_to` — this protects payload integrity in transit.
* **Validate the payload shape** on your side before trusting it. Reject requests that don't match Meta's documented schema.
* **IP allowlist if possible.** Xobito forwards from the same server that talks to Meta — keep that server's egress IPs in a short list and allow only those.
* **Rotate the URL** if you believe it's leaked. Treat the URL itself as a weak secret.
* **Don't trigger destructive actions** (deletes, refunds) directly from a forwarded event without a second check — poll Xobito's API to confirm before acting.

## Meta fields you can forward

Xobito enumerates 30+ Meta webhook fields in the settings page. Pick only what you need — each extra field ticked means more traffic to your endpoint.

<AccordionGroup>
  <Accordion title="Account & business">
    Fire when your WhatsApp Business Account state changes — useful for compliance and ops dashboards.

    | Field                        | Fires when                                                |
    | ---------------------------- | --------------------------------------------------------- |
    | `account_alerts`             | Meta issues an alert against your WABA                    |
    | `account_review_update`      | Your WABA completes / fails a review                      |
    | `account_settings_update`    | Business-level settings change (display name, profile)    |
    | `account_update`             | Generic account state change                              |
    | `business_capability_update` | Your business-tier limits change (messaging tier up/down) |
    | `business_status_update`     | Your business verification or status changes              |
  </Accordion>

  <Accordion title="Calls">
    | Field   | Fires when                                                      |
    | ------- | --------------------------------------------------------------- |
    | `calls` | A WhatsApp call event occurs (if your WABA has calling enabled) |
  </Accordion>

  <Accordion title="Flows">
    | Field   | Fires when                                                                          |
    | ------- | ----------------------------------------------------------------------------------- |
    | `flows` | A WhatsApp Flow is submitted by the customer — you receive the structured responses |
  </Accordion>

  <Accordion title="History">
    | Field     | Fires when                                                                     |
    | --------- | ------------------------------------------------------------------------------ |
    | `history` | Meta sends historical conversation context (e.g. after re-connecting a number) |
  </Accordion>

  <Accordion title="Message events">
    The highest-volume category. Think twice before enabling all of them.

    | Field                                | Fires when                                                                  |
    | ------------------------------------ | --------------------------------------------------------------------------- |
    | `messages`                           | An incoming message from a customer — text, media, button clicks, reactions |
    | `message_echoes`                     | Your own outbound message is echoed back (for multi-client sync)            |
    | `web_message_echoes`                 | WhatsApp Web echoes (multi-device sessions)                                 |
    | `message_template_components_update` | A template's components change approval state                               |
    | `message_template_quality_update`    | A template's quality rating changes                                         |
    | `message_template_status_update`     | A template's approval status changes                                        |
    | `messaging_handovers`                | A message is handed over between apps (two-app inbox)                       |
  </Accordion>

  <Accordion title="Message status & quality">
    | Field                         | Fires when                                                    |
    | ----------------------------- | ------------------------------------------------------------- |
    | `phone_number_quality_update` | Your phone number's quality rating changes (green/yellow/red) |
    | `phone_number_name_update`    | Your display name changes or is re-approved                   |
    | `security`                    | A security-related event on your WABA                         |
    | `template_category_update`    | A template is recategorised by Meta                           |
  </Accordion>

  <Accordion title="Groups">
    Fire for WhatsApp group-related updates (where your number participates). Each of the four sub-fields ticks independently.

    | Field                       | Fires when                                            |
    | --------------------------- | ----------------------------------------------------- |
    | `group_lifecycle_update`    | A group is created / deleted                          |
    | `group_participants_update` | A member joins or leaves                              |
    | `group_settings_update`     | Group settings change (name, description, admin list) |
    | `group_status_update`       | Group status changes                                  |
  </Accordion>

  <Accordion title="Payment">
    | Field                          | Fires when                                         |
    | ------------------------------ | -------------------------------------------------- |
    | `payment_configuration_update` | Your WhatsApp Pay / payments configuration changes |
  </Accordion>

  <Accordion title="Other">
    | Field               | Fires when                                                     |
    | ------------------- | -------------------------------------------------------------- |
    | `automatic_events`  | Meta-originated automatic events on your WABA                  |
    | `partner_solutions` | Partner-solution provisioning / status events                  |
    | `web_app_data_sync` | WhatsApp Web / multi-device sync events                        |
    | `tracking_events`   | Attribution / click-tracking events                            |
    | `user_preferences`  | A user's WhatsApp preferences change (marketing opt-outs etc.) |
  </Accordion>
</AccordionGroup>

<Tip>
  Don't tick every box "just in case". Start with `messages` + `phone_number_quality_update` + `template_quality_update` — those cover most integration needs. Add more as you discover gaps.
</Tip>

## Sample forwarded payload

Xobito forwards Meta's payload as-is. Below is a representative example of an incoming-message event (`messages` field) for reference only — the exact shape is defined by Meta and can change.

<CodeGroup>
  ```json Incoming message theme={null}
  {
    "object": "whatsapp_business_account",
    "entry": [
      {
        "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
        "changes": [
          {
            "field": "messages",
            "value": {
              "messaging_product": "whatsapp",
              "metadata": {
                "display_phone_number": "15551234567",
                "phone_number_id": "PHONE_NUMBER_ID"
              },
              "contacts": [
                {
                  "profile": { "name": "Jane Doe" },
                  "wa_id": "15559998888"
                }
              ],
              "messages": [
                {
                  "from": "15559998888",
                  "id": "wamid.HBgMMTU1NTk5OTg4ODgVAgASGBQzRURFRg==",
                  "timestamp": "1713266400",
                  "type": "text",
                  "text": { "body": "Is the order ready?" }
                }
              ]
            }
          }
        ]
      }
    ]
  }
  ```

  ```json Template quality update theme={null}
  {
    "object": "whatsapp_business_account",
    "entry": [
      {
        "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
        "changes": [
          {
            "field": "template_quality_update",
            "value": {
              "previous_quality_score": "GREEN",
              "new_quality_score": "YELLOW",
              "message_template_id": 123456789,
              "message_template_name": "order_shipped",
              "message_template_language": "en_US"
            }
          }
        ]
      }
    ]
  }
  ```
</CodeGroup>

<Note>
  Consult [Meta's Cloud API webhook reference](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components) for the authoritative schema of each field.
</Note>

## Testing your endpoint

There is **no built-in "Send test webhook" button** on the Xobito settings page. To verify end-to-end you need to trigger a real Meta event. Practical ways:

* **Messages:** send a WhatsApp message from a test phone to your business number.
* **Template quality:** this is out of your control — rely on the `messages` test for wiring, and add monitoring for quality events later.
* **Phone number quality:** same — wire it now, observe in production.

<Tip>
  Point `whatsapp_data_resend_to` at a free request-inspection service (e.g. webhook.site) when you first set up. Once payloads look right, switch to your real endpoint.
</Tip>

## Flow A — Outbound CRUD webhooks (summary)

Configured in the **same settings page** but under the **Webhook URL / events** section. Fires on contact/status/source create/update/delete events inside your workspace. Signed with HMAC-SHA256, up to 3 attempts with 1s and 2s waits between retries, 30-second timeout.

See the full guide and payload schema at [Webhooks Overview](/developers/webhooks-overview). Security and signature verification at [Webhook Security](/developers/webhook-security). Full event catalogue at [Webhook Events](/developers/webhook-events).

## Troubleshooting

<AccordionGroup>
  <Accordion title="I saved the settings but nothing arrives at my URL">
    Check, in order:

    1. Is **Enable Webhook Resend** on?
    2. Have you ticked at least one field?
    3. Has a matching Meta event actually happened? (e.g. you ticked `messages` — send a message from a test phone.)
    4. Is your URL reachable from the public internet over HTTPS? Try a `curl -X POST` from another network to confirm.
    5. Is your endpoint returning a 2xx? Some receivers reject unknown content types.
  </Accordion>

  <Accordion title="My endpoint returns 5xx — does Xobito retry?">
    Flow B has **no documented retry policy**. Build your receiver to be resilient:

    * Respond 200 fast, queue the payload internally, then process asynchronously.
    * If you need delivery guarantees, consider polling Xobito's API to fill gaps, or use Flow A for the records you care about.
  </Accordion>

  <Accordion title="TLS / HTTPS errors">
    * Make sure your certificate is issued by a public CA (Let's Encrypt, DigiCert, etc.) — self-signed certs may be rejected.
    * Ensure your hostname matches the certificate's SAN.
    * Disable HTTP/2-only features if your backend can't handle Meta-scale throughput.
  </Accordion>

  <Accordion title="I'm getting too many events">
    You probably ticked high-volume fields like `messages` or `message_echoes`. Narrow the selection or move event handling to a queue on your side.
  </Accordion>

  <Accordion title="Payloads look different from Meta's docs">
    Meta periodically updates its webhook schemas. Always validate incoming payloads defensively and log unexpected shapes rather than crashing.
  </Accordion>

  <Accordion title="I need a signature / HMAC on forwarded events">
    Not supported in the current version. Mitigations:

    * Use HTTPS + IP allowlist.
    * Treat the destination URL itself as a weak shared secret (rotate if leaked).
    * If signature verification is a hard requirement, use Flow A for the Xobito-originated records you care about — those are signed.
  </Accordion>
</AccordionGroup>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I forward to multiple URLs?">
    No — Flow B supports a single destination URL. If you need fan-out, deliver to one endpoint and re-broadcast from there (e.g. a small Lambda / worker).
  </Accordion>

  <Accordion title="Can I filter events by phone number or content?">
    No — filtering is at the *field* level only. Your receiver must do any finer-grained filtering (e.g. "only messages from VIP contacts").
  </Accordion>

  <Accordion title="Does disabling the resend toggle delete my field selections?">
    No. Your ticked fields are kept. Turning the master toggle back on resumes forwarding with the same selection.
  </Accordion>

  <Accordion title="Will Xobito stop processing events if my URL is down?">
    No. Flow B is a best-effort *copy* of events. Xobito's own processing of Meta events (so the dashboard, campaigns, and bots keep working) is independent of forwarding.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Webhooks Overview" icon="webhook" href="/developers/webhooks-overview">
    Flow A — outbound CRUD webhooks, signed, retried, ready for CRM sync.
  </Card>

  <Card title="Webhook Events" icon="list" href="/developers/webhook-events">
    Full catalogue of Flow A event payloads, field-by-field.
  </Card>

  <Card title="Webhook Security" icon="shield-check" href="/developers/webhook-security">
    How to verify HMAC-SHA256 signatures on Flow A.
  </Card>

  <Card title="Meta's Cloud API webhooks" icon="arrow-up-right-from-square" href="https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components">
    Authoritative schema for every Flow B payload.
  </Card>
</CardGroup>