## Overview

Many platform modules emit **events** when something changes — a conversation is created, a payment is
confirmed, a deal changes stage, etc. You can react to these events via **webhooks** or through the
internal **automation rules**.

## Prerequisites

- Configured webhooks (for external consumption) or Automation access (for internal reactions).

## Step by step

1. Identify the module event you want to consume (e.g., conversation created, payment paid).
2. For external consumption: subscribe to the event in the webhook and handle the payload at your endpoint.
3. For internal reactions: create an automation rule with the matching trigger.
4. Validate and process the payload idempotently.

## Settings & options

- **Webhooks**: subscription per inbox/account.
- **Automation**: per-event triggers, with conditions and actions.
- **Payload**: contains the event context (ids and relevant data).

### New per-module events (real payloads)

The fields below come from each event's real source — don't invent the format. All are delivered to
**account webhooks**; calls and Flow responses also go to the **API channel** webhook. Delivery of
each group requires the **module feature enabled** on the account (the subscription works even with
the feature off, but nothing is delivered).

### Team Management — feature: Team Management

- `wfm_status_changed`, `wfm_break_started` — the agent changed status / started a break. Fields:
  `account_id`, `account_user_id`, `user_id`, `status_key`, `status_event_id`, `base_availability`, `family`.
- `wfm_break_breached` — the break exceeded its limit. Fields: the above plus `expected_seconds` and `over_by_seconds`.
- `wfm_break_ended` — the agent left a break (any path: manual switch, native dropdown or auto-offline).
  Fields: the break-start fields plus `duration_seconds`, `within_limit` and, when breached, `over_by_seconds`.
- `wfm_shift_started`, `wfm_shift_ended` — the agent's planned shift window opened/closed (evaluated server-side
  every minute). Fields: `account_id`, `account_user_id`, `user_id`, `shift_id`, `schedule_id` (when generated
  from a template), `date`, `starts_at`, `ends_at`. Each lifecycle event fires exactly once per shift.

### WhatsApp Hub broadcasts — feature: WhatsApp Hub

- `whatsapp_broadcast_started`, `whatsapp_broadcast_completed`, `whatsapp_broadcast_failed` — the broadcast
  changed state. Fields (no message content): `account_id`, `inbox_id`, `broadcast_id`, `display_id`,
  `title`, `status`, `target_type`, `recipients_count`. Works on Cloud and WazMeow (WhatsApp Web) inboxes.

### WhatsApp group welcome and farewell greetings — feature: WhatsApp Hub

- `whatsapp_group_member_welcomed`, `whatsapp_group_member_farewelled` — fire **only when** the welcome/farewell
  message was actually sent (idempotent, once per participant per dedup window). Fields: `account_id`, `inbox_id`,
  `whatsapp_group_id`, `group_jid`, `participant_jid`, `participant_phone`, `trigger` (`welcome` or `farewell`).
  No message content.

### Ads Manager — feature: Growth Ads or Ads Manager

- `ads_campaign_status_changed` — a mirrored campaign's effective status changed. Fields: `account_id`,
  `ad_account_id`, `campaign_id`, `remote_id`, `status`, `effective_status`, `previous_effective_status`.
- `ctwa_conversation_started` — a Click-to-WhatsApp conversation started (fired on the customer's message). At that point the ad window is awaiting the first reply, and `expires_at` is the **24-hour deadline to reply**. If the business replies within that deadline, the free window opens for up to 7 days, or until the exact end Meta reports. Fields:
  `account_id`, `conversation_id`, `contact_id`, `inbox_id`, `window_id`, `expires_at`.
- `ad_window_expiring` — that window is near expiry. Same fields.

### WhatsApp calls and Flow responses — feature: WhatsApp Inbox Suite

- `whatsapp_call_started`, `whatsapp_call_ended`, `whatsapp_call_recording_ready` — the call lifecycle. Fields
  (which are present depends on the stage): `provider_call_id`, `conversation_id`, `realtime`, `status`,
  `recording_url`. Delivered to account and API-channel webhooks.
  For browser recording, `whatsapp_call_recording_ready` is emitted after audio recording is enabled
  for the inbox and the uploaded audio is saved in storage. Ending the call alone does not emit it.
  The webhook must subscribe to this event; `recording_url` points to the available recording.
- `whatsapp_flow_response_received` — a customer completed a WhatsApp Flow. Fields: the `flow_response` object
  (`id`, `whatsapp_flow_id`, `screen`, `response`, `contact_id`, `conversation_id`) and the `conversation` object.
  Delivered to account and API-channel webhooks.

### FlowBuilder sessions — feature: Flow Builder

- `flow_session_started`, `flow_session_updated`, `flow_session_completed`, `flow_session_failed` — the flow
  session started, paused, completed or failed. Fields: `id`, `flow_id`, `status`, `current_node_id`,
  `conversation_id`, `account_id`.

## Use cases

- Update an external system when a payment is confirmed.
- Trigger a follow-up cadence when a deal changes stage.

## Tips, limits & best practices

- Always check the real payload source before mapping fields (don't invent the format).
- Ensure idempotency by event identifier.

## Troubleshooting

- **Event not arriving**: confirm the subscription and the endpoint status.
- **Unexpected fields**: review the actual received payload and adjust the mapping.

## See also

- [REST API, tokens and webhooks](/hc/ajuda/articles/api-developers-rest-tokens-webhooks-en)
- [Automation rules](/hc/ajuda/articles/automation-flows-regras-de-automacao-en)
- [API channel: the structured event contract](/hc/ajuda/articles/api-developers-api-channel-contract-en)