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

# Meta Webhooks

> How Galantis receives inbound messages, message status updates, and template status changes from Meta via webhooks.

Meta sends webhooks to Galantis for three categories of events: inbound messages from customers, outbound message status updates, and template status changes. These webhooks are the real-time data feed from Meta back into Galantis — they are what makes the Inbox live, what populates campaign and automation analytics with delivery data, and what keeps template approval status current.

## What this covers

* The three Meta webhook event categories and what each delivers
* How inbound messages are processed into Inbox conversations
* How message status updates power analytics and automation conditions
* How template status changes update Galantis automatically
* Security validation and retry behavior

## Meta webhook event categories

### Inbound messages

**Event:** `messages` (inbound)

**Payload:** Message object containing sender phone number, message content (text, media, or interactive reply), and context (which message the customer is replying to, if any).

**What Galantis does:**

When an inbound message webhook arrives, Galantis:

1. Validates the webhook signature
2. Identifies the customer by their phone number — matching against contact records in Galantis
3. Creates or updates a `Conversation` record for the customer
4. Creates a `Message` record with the inbound message content
5. Dispatches the `ConversationMessageCreated` event
6. Broadcasts the new message to the merchant dashboard in real time — agents see the message appear in the Inbox immediately without refreshing

The inbound message also opens or resets the 24-hour conversation window for that customer. See [Compliance — Conversation Window](/whatsapp/compliance/conversation-window).

**QUICK\_REPLY responses:** When a customer taps a `QUICK_REPLY` button in a template message, the response arrives as an inbound message webhook with the button's reply payload. Automation condition nodes using `USER_REPLY_STATUS` evaluate against these reply events.

**STOP responses:** When a customer replies STOP, the inbound message webhook is received, the reply is processed, and the customer's `marketing_state` is immediately updated to `UNSUBSCRIBED`. See [Audience — Consent & Opt-outs](/whatsapp/audience/consent-optouts).

***

### Message status updates

**Event:** `message_status`

**Payload:** Status update containing the message ID, the new status (`sent`, `delivered`, `read`, `failed`), and a timestamp.

**Status progression:**

```
sent → delivered → read
              ↓
           failed (at any stage)
```

**What Galantis does:**

When a message status webhook arrives:

1. Galantis matches the message ID to the corresponding `Message` record
2. Updates `Message.status` and the relevant status timestamp field
3. Aggregates the updated status into campaign-level or automation-level analytics

This is the mechanism that populates the `SENT`, `DELIVERED`, `READ`, and `FAILED` counts in campaign analytics and automation activity logs. Status updates arrive asynchronously — a campaign's analytics populate gradually as Meta sends callbacks for each message in the send batch.

**`played` status:** For audio and video messages, Meta sends a `played` status in addition to `read`. Galantis records this status on the `Message` model.

**`failed` status:** A failed status includes an error code and description from Meta indicating why delivery failed. Common failure codes (`CUSTOMER_IS_NOT_OPTED_IN`, `CUSTOMER_IS_MISSING_CALLING_CODE`) are exposed in campaign analytics and automation activity logs as human-readable error reasons.

**Automation condition evaluation:** The `MESSAGE_DELIVERY_STATUS` condition type in automation flows evaluates against the delivery status recorded via these webhooks. A condition checking whether the last message was "read" evaluates against the `read` status update received here.

***

### Template status changes

**Event:** `message_template_status_update`

**Payload:** Template identifier and new status — `approved`, `rejected`, or `paused`.

**What Galantis does:**

When a template status change webhook arrives:

1. Galantis matches the template identifier to the corresponding `MessageTemplate` record
2. Updates `MessageTemplate.status` to reflect the new state
3. If the template has moved to `APPROVED`, it becomes immediately available for use in campaigns and automation Action Nodes
4. If the template has moved to `REJECTED` or `PAUSED`, any active automations using it begin failing at the affected Action Node on subsequent customer executions — the automation is not automatically deactivated

This webhook-based status sync means merchants do not need to manually poll for template approval results. When Meta completes a review, the status in Galantis updates automatically — typically within minutes of the review completing.

## Security validation

All incoming Meta webhooks are validated via signature verification before processing. Meta includes a cryptographic signature in the webhook request headers, computed from the payload using the app secret. Galantis verifies this signature before passing the payload to any handler — requests with invalid or missing signatures are rejected immediately and never processed.

This validation prevents replay attacks and unauthorized webhook injection from sources other than Meta.

## Retry behavior

If Galantis fails to process a Meta webhook — due to a temporary server error, a processing issue, or an application exception — the failed processing is retried automatically with exponential backoff. This means a transient error does not permanently lose a webhook event.

Meta also retries webhook delivery from its side if the initial delivery attempt receives an error response. Combined with Galantis's own retry behavior, the system is resilient to most temporary failures in the processing pipeline.

<Note>
  If Galantis is unavailable for an extended period — longer than Meta's webhook delivery retry window — some webhook events may not be recoverable from Meta's side. In this case, message status updates may be missing from analytics for messages sent during the outage window, and inbound messages received during the outage may not appear in the Inbox. This is an edge case that applies only to extended outages, not to normal transient errors.
</Note>

## Related guides

* [Inbox — Conversation Lifecycle](/whatsapp/inbox/conversation-lifecycle) — How inbound message webhooks create and update conversations
* [Compliance — Conversation Window](/whatsapp/compliance/conversation-window) — How inbound messages open and reset the 24-hour window
* [Campaign Analytics](/whatsapp/campaigns/campaign-analytics) — How status update webhooks populate delivery metrics
* [Templates — Approval Lifecycle](/whatsapp/templates/approval-lifecycle) — How template status webhooks update template state in Galantis