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

> How Xobito's webhook from Meta works, why you don't have to configure it manually, and how to verify it's delivering events.

Webhooks are how Xobito knows that a customer just messaged you, a delivery receipt came back, or a template was approved. This page explains what they are, how Xobito sets them up automatically, and how to confirm they're working.

<Note>
  **The short version:** you don't have to do anything. Xobito configures the Meta → Xobito webhook for you during [Connect Meta Business](/whatsapp/connect-meta-business). This page is for when you want to verify it or troubleshoot.
</Note>

## What's a webhook, in plain English?

A webhook is a URL that one system calls when something happens, so another system hears about it in real time — no polling, no delays.

In your case, Meta needs to tell Xobito:

* "A new message just came in for your number."
* "That message you sent was delivered."
* "It was read."
* "Your template was just approved by our review team."
* "Your phone number's quality rating changed."

Meta does this by sending a small **HTTP POST request** to a URL Xobito registered during connection. The URL is something like:

```
https://dash.xobito.com/api/webhooks/whatsapp/{your-workspace-id}
```

Each request carries a JSON payload describing what happened.

<Info>
  This is the **inbound** direction only — Meta → Xobito. It has nothing to do with any "outbound webhooks" you may later configure from Xobito to your own systems. Those are documented in the [Developer section](/developers/webhooks-overview).
</Info>

## Why it's automatic

Traditionally, configuring webhooks meant copy-pasting a callback URL and a verify token into Meta Business Manager, choosing which events to subscribe to, and hoping you matched it all correctly.

Xobito eliminates all of that. During the [embedded signup](/whatsapp/connect-meta-business):

1. You click **Login with Facebook** and approve permissions.
2. Meta issues Xobito an access token.
3. Xobito uses that token to **register our webhook URL** and **subscribe** your WABA to the events we need: messages, statuses, templates, phone numbers.
4. Meta starts delivering events immediately.

<Tip>
  If you ever need to see or re-confirm the webhook, go to **Setup → Account**, click the connected WABA row, and look at the **Webhook** section.
</Tip>

## The events Xobito subscribes to

Xobito listens for these Meta event fields:

| Event field                       | What it tells us                                  |
| --------------------------------- | ------------------------------------------------- |
| `messages`                        | A new inbound message from a customer.            |
| `message_template_status_update`  | Your template was approved, rejected, or paused.  |
| `message_template_quality_update` | Meta adjusted the quality of a specific template. |
| `phone_number_quality_update`     | Your number's Green/Yellow/Red rating changed.    |
| `phone_number_name_update`        | Your display name was approved or rejected.       |
| `account_update`                  | WABA-level status changes.                        |
| `account_review_update`           | Results of an account review.                     |
| `business_capability_update`      | Messaging tier or other capability changed.       |

When any of these fire, Xobito updates your UI, triggers notifications, and runs any matching automations.

## Verify the webhook is working

**To verify the incoming webhook is wired:** send yourself a WhatsApp message from a phone the workspace doesn't know — within 2–5 seconds the conversation should appear in the Live Inbox. If it doesn't, see [Troubleshooting](/troubleshooting/message-delivery).

<Check>If the inbound message lands in the Live Inbox, your webhook is healthy.</Check>

## When the webhook breaks

Webhooks almost never "break" — but a few scenarios can interrupt them:

<CardGroup cols={2}>
  <Card title="You revoked Xobito's permissions in Meta" icon="ban">
    If you removed Xobito from your Business Manager, the webhook stops. Fix: reconnect via **Setup → Connect WhatsApp**.
  </Card>

  <Card title="Your Meta access token expired" icon="clock">
    Rare, but possible for long-idle accounts. Fix: reconnect.
  </Card>

  <Card title="Meta platform outage" icon="cloud-bolt">
    Every few months Meta has a short incident. No fix needed — events resume once Meta is back. They retry failed deliveries automatically.
  </Card>

  <Card title="Xobito webhook endpoint unreachable" icon="server">
    Extremely rare. Our platform is monitored 24/7. If it happens, Meta retries for up to 7 days.
  </Card>
</CardGroup>

## How Xobito detects a broken webhook

If your WABA has been silent for an unusually long time **and** Xobito expects messages to be flowing, the Account page will surface a warning banner.

<Tip>
  You never need to "keep checking" — Xobito will surface any webhook issue directly in **Setup → Account** and by email to your workspace admins.
</Tip>

### Re-establish the webhook

If the banner is showing, or you just want to re-register to be safe, run the [Connect Meta Business](/whatsapp/connect-meta-business) flow again — this re-issues the access token and re-subscribes your WABA to the required events.

<Warning>
  If reconnecting fails with an authorization error, your Meta access token is no longer valid. Run [Connect Meta Business](/whatsapp/connect-meta-business) again to get a fresh token.
</Warning>

## Can I use my own webhook URL instead?

No — the Meta → Xobito webhook **must** point at Xobito. If it pointed somewhere else, Xobito couldn't show you inbound messages or track campaign delivery.

What you **can** do is configure **outbound webhooks** from Xobito to your own systems. Those forward relevant events from Xobito to any URL you specify — great for syncing WhatsApp conversations into your CRM, helpdesk, or data warehouse. See [Developer → Webhooks](/developers/webhooks-overview).

## Security of inbound webhooks

Every event Meta sends to Xobito is:

<Check>**Signed** with an HMAC signature that Xobito verifies using a shared secret.</Check>
<Check>**Delivered over HTTPS** — events never travel in the clear.</Check>
<Check>**Matched to your workspace** via the unique webhook URL path.</Check>

If Meta ever sends an event whose signature doesn't match, Xobito drops it silently — a malicious party can't forge events into your inbox.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Messages aren't reaching my Xobito inbox, but I can send fine">
    Classic webhook issue. Go to **Setup → Account**, look for a warning banner, and reconnect via [Connect Meta Business](/whatsapp/connect-meta-business). If the problem persists after reconnecting, contact support.
  </Accordion>

  <Accordion title="Inbound messages never reach my workspace even though I just got a message on my phone">
    The most common cause is a partial or interrupted connect flow. Fix: disconnect and reconnect. Go to **Setup → Account**, click **Disconnect**, then run Connect WhatsApp again. See [Disconnect](/whatsapp/disconnect) for what that resets.
  </Accordion>

  <Accordion title="I see 'Webhook registration failed' immediately after connecting">
    Usually a transient Meta error. Wait 5 minutes, then re-run [Connect Meta Business](/whatsapp/connect-meta-business). If it still fails, capture the error text and contact support.
  </Accordion>

  <Accordion title="How do I test my webhook without bothering a real contact?">
    Send a WhatsApp message to your connected business number from a personal phone (or a colleague's) that isn't already in your contact list. The new conversation should appear in the Live Inbox within a few seconds — that confirms inbound delivery is healthy.
  </Accordion>

  <Accordion title="Does Xobito ever 'lose' events?">
    Very rarely. Meta retries failed deliveries for up to 7 days, and Xobito acknowledges every successful receipt. If we ever do miss an event (e.g. our servers were briefly offline), Meta's retry queue delivers it when we're back.
  </Accordion>

  <Accordion title="I see events in the log I don't recognize">
    Meta occasionally introduces new event types. If you see one that's labeled "unhandled" in the log, it's a Meta event Xobito hasn't mapped yet — it doesn't indicate a problem with your account.
  </Accordion>
</AccordionGroup>

## Where to go next

<CardGroup cols={2}>
  <Card title="Phone numbers" icon="phone" href="/whatsapp/phone-numbers">
    Manage display name, quality, and messaging tier.
  </Card>

  <Card title="Developer webhooks" icon="code" href="/developers/webhooks-overview">
    Push Xobito events to your own systems.
  </Card>

  <Card title="Disconnect a WABA" icon="plug-circle-xmark" href="/whatsapp/disconnect">
    Cleanly unlink your account and understand what happens to data.
  </Card>
</CardGroup>