Webhook Settings

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.
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
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	This page

When to use Flow A vs Flow B

Use Flow A when...

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.

Use Flow B when...

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.

Flows are independent. You can enable neither, one, or both.

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

Open Settings → Webhook Settings

Sidebar → Settings → Webhook Settings.

Turn on 'Enable Webhook Resend'

Flip the master toggle. Until this is on, nothing is forwarded.

Enter your destination URL

Paste the full HTTPS URL of the endpoint that should receive the events.

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.

Select which Meta fields to forward

Tick the boxes next to the event fields you care about. Leave the rest unticked to avoid noise.

Save

Changes take effect immediately. The next matching Meta event will be re-posted to your URL.

Field reference

enable_webhook_resend

boolean

default:"false"

Master on/off switch. When false, no events are forwarded regardless of which fields are ticked.

whatsapp_data_resend_to

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.

webhook_resend_method

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

webhook_selected_fields

array

JSON array of Meta webhook field slugs to forward — see the full list below. Only ticked fields are forwarded; everything else Xobito receives from Meta is handled internally and not re-posted.

All input is sanitised via Xobito’s PurifiedInput rule (strips control characters, normalises whitespace). Very long labels or URLs are rejected at 255 characters.

Security of forwarded events

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.

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.

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

Calls

Field	Fires when
`calls`	A WhatsApp call event occurs (if your WABA has calling enabled)

Flows

Field	Fires when
`flows`	A WhatsApp Flow is submitted by the customer — you receive the structured responses

History

Field	Fires when
`history`	Meta sends historical conversation context (e.g. after re-connecting a number)

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)

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

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

Payment

Field	Fires when
`payment_configuration_update`	Your WhatsApp Pay / payments configuration changes

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

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.

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.

{
  "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?" }
              }
            ]
          }
        }
      ]
    }
  ]
}

Consult Meta’s Cloud API webhook reference for the authoritative schema of each field.

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.

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.

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. Security and signature verification at Webhook Security. Full event catalogue at Webhook Events.

Troubleshooting

I saved the settings but nothing arrives at my URL

Check, in order:

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

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.

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.

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.

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.

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.

Frequently asked questions

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

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”).

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.

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.

Next steps

Webhooks Overview

Flow A — outbound CRUD webhooks, signed, retried, ready for CRM sync.

Webhook Events

Full catalogue of Flow A event payloads, field-by-field.

Webhook Security

How to verify HMAC-SHA256 signatures on Flow A.

Meta's Cloud API webhooks

Authoritative schema for every Flow B payload.

​The two flows at a glance

​When to use Flow A vs Flow B

Use Flow A when...

Use Flow B when...

​Flow B — Meta webhook forwarder

​Enable forwarding

​Field reference

​Security of forwarded events

​Meta fields you can forward

​Sample forwarded payload

​Testing your endpoint

​Flow A — Outbound CRUD webhooks (summary)

​Troubleshooting

​Frequently asked questions

​Next steps

Webhooks Overview

Webhook Events

Webhook Security

Meta's Cloud API webhooks

The two flows at a glance

When to use Flow A vs Flow B

Flow B — Meta webhook forwarder

Enable forwarding

Field reference

Security of forwarded events

Meta fields you can forward

Sample forwarded payload

Testing your endpoint

Flow A — Outbound CRUD webhooks (summary)

Troubleshooting

Frequently asked questions

Next steps