Skip to main content

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 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 via Laravel Reverb — 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. 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.

​
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 database issue, or an application exception — the failed processing is retried via Laravel’s queue retry mechanism 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 queue retry behavior, the system is resilient to most temporary failures in the processing pipeline.
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.