Flows notifications

Last update: 5 hours ago by Irais Aguirre

Integration summary
Delivery: WhatsApp → Concepto Móvil → POST to the platform webhook configured for the account (not the per-number webhook), with a JSON body. Only delivered when the account has a platform configured.
Headers: Content-Type: application/json; charset=UTF-8 and optional Authorization: Basic …. No Cache-Control is sent.
Retries: not retried on HTTP error responses; only retried on I/O errors.
Format: Meta's full webhook object (object, entry, changes), with field set to "flows" (see Webhook).
Types on this page: FLOW_STATUS_CHANGE, CLIENT_ERROR_RATE, ENDPOINT_ERROR_RATE, ENDPOINT_LATENCY, ENDPOINT_AVAILABILITY, FLOW_VERSION_EXPIRY_WARNING (event values)

For the response a user sends after completing a Flow, see WhatsApp Flows in Interactive replies.

General structure

Flows notifications (status changes and alerts for a Flow) are delivered by webhook. They are a combination of nested JSON arrays and objects that contain information about a change.

Structure

Fields for General structure:

Name	Description	Type
object	The webhook the business is subscribed to.	String
entry	An array of entry objects. Entry objects have the following properties: `id` (String). The ID of the WhatsApp Business Account subscribed to the webhook. `changes` (Object). An array of change objects. Change objects have the following properties: `value` (Object). `field` (String). flows	Object list

Value object

Contains the details of the change that triggered the webhook. This object is nested inside the changes array of the entry array.

Name	Description	Type
flow_id	Flow ID.	String
threshold	The alert threshold that was reached.	Number
event	Notification type. Possible values: FLOW_STATUS_CHANGE CLIENT_ERROR_RATE ENDPOINT_ERROR_RATE ENDPOINT_LATENCY ENDPOINT_AVAILABILITY FLOW_VERSION_EXPIRY_WARNING	String
message	Detailed description of the message.	String
old_status	Previous Flow status: DRAFT PUBLISHED DEPRECATED BLOCKED THROTTLED	String
new_status	Current Flow status: DRAFT PUBLISHED DEPRECATED BLOCKED THROTTLED	String
alert_state	Alert status: ACTIVATED DEACTIVATED	String
requests_count	Number of requests used to calculate the metric.	Integer
errors	An array of error objects describing each error included in the alert. Error objects have the following properties: `error_count` (Integer). Number of times the error occurred. `error_rate` (Number, decimal). Error rate for that specific error. `error_type` (String). Error name.	Object list
p50_latency	P50 latency of endpoint requests.	Integer
p90_latency	P90 latency of endpoint requests.	Integer
error_rate	Overall error rate for the alert.	Number (decimal)
availability	Flow endpoint availability (percentage).	Number
warning	Freeze or expiry warning for the Flow version. Present in `FLOW_VERSION_EXPIRY_WARNING` events and, on Flow creation, it can also appear in a `FLOW_STATUS_CHANGE` event.	String

Flow status change

The event field is "FLOW_STATUS_CHANGE".

Example

Complete Flow status change example:

Flow created

{
    "entry": [
        {
            "id": "173276950931742",
            "time": 1718654293,
            "changes": [
                {
                    "value": {
                        "event": "FLOW_STATUS_CHANGE",
                        "message": "Flow Flow for Customer Support New has been created with DRAFT status",
                        "flow_id": "474277461763971",
                        "new_status": "DRAFT"
                    },
                    "field": "flows"
                }
            ]
        }
    ],
    "object": "whatsapp_business_account"
}

From DRAFT to PUBLISHED

{
    "entry": [
        {
            "id": "173276950931742",
            "time": 1718663619,
            "changes": [
                {
                    "value": {
                        "event": "FLOW_STATUS_CHANGE",
                        "message": "Flow My survey flow changed status from DRAFT to PUBLISHED",
                        "flow_id": "1191878175570507",
                        "old_status": "DRAFT",
                        "new_status": "PUBLISHED"
                    },
                    "field": "flows"
                }
            ]
        }
    ],
    "object": "whatsapp_business_account"
}

From PUBLISHED to DEPRECATED

{
    "entry": [
        {
            "id": "173276950931742",
            "time": 1718728797,
            "changes": [
                {
                    "value": {
                        "event": "FLOW_STATUS_CHANGE",
                        "message": "Flow dev_prueba_2 changed status from PUBLISHED to DEPRECATED",
                        "flow_id": "1504323267150344",
                        "old_status": "PUBLISHED",
                        "new_status": "DEPRECATED"
                    },
                    "field": "flows"
                }
            ]
        }
    ],
    "object": "whatsapp_business_account"
}

CLIENT_ERROR_RATE

The event field is "CLIENT_ERROR_RATE".

Example

Complete CLIENT_ERROR_RATE example:

{
    "entry": [
        {
            "id": "106181168862417",
            "time": 1674160476,
            "changes": [
                {
                    "value": {
                        "event": "CLIENT_ERROR_RATE",
                        "message": "The flow client request error rate has reached the 5% threshold in the last 60 minutes. A higher error rate will make it harder for users to complete the flow, resulting in drop-offs.",
                        "flow_id": "691244242662581",
                        "error_rate": 14.28,
                        "threshold": 10,
                        "alert_state": "ACTIVATED",
                        "errors": [
                            {
                                "error_type": "INVALID_SCREEN_TRANSITION",
                                "error_rate": 66.66,
                                "error_count": 2
                            },
                            {
                                "error_type": "PUBLIC_KEY_MISSING",
                                "error_rate": 33.33,
                                "error_count": 1
                            }
                        ]
                    },
                    "field": "flows"
                }
            ]
        }
    ],
    "object": "whatsapp_business_account"
}

ENDPOINT_ERROR_RATE

The event field is "ENDPOINT_ERROR_RATE".

Example

Complete ENDPOINT_ERROR_RATE example:

{
    "entry": [
        {
            "id": "106181168862417",
            "time": 1674160476,
            "changes": [
                {
                    "value": {
                        "event": "ENDPOINT_ERROR_RATE",
                        "message": "The flow endpoint request error rate has reached the 10% threshold in the last 30 minutes. A higher error rate will make it harder for users to complete the flow, resulting in drop-offs.",
                        "flow_id": "691244242662581",
                        "error_rate": 14.28,
                        "threshold": 10,
                        "alert_state": "ACTIVATED",
                        "errors": [
                            {
                                "error_type": "CAPABILITY_ERROR",
                                "error_rate": 66.66,
                                "error_count": 2
                            },
                            {
                                "error_type": "TIMEOUT",
                                "error_rate": 33.33,
                                "error_count": 1
                            }
                        ]
                    },
                    "field": "flows"
                }
            ]
        }
    ],
    "object": "whatsapp_business_account"
}

ENDPOINT_LATENCY

The event field is "ENDPOINT_LATENCY".

Example

Complete ENDPOINT_LATENCY example:

{
    "entry": [
        {
            "id": "106181168862417",
            "time": 1674160476,
            "changes": [
                {
                    "value": {
                        "event": "ENDPOINT_LATENCY",
                        "message": "Flow endpoint latency has reached the p90 threshold in the last 30 minutes. High latency will increase the loading time between screens in the flow, impacting user experience.",
                        "flow_id": "691244242662581",
                        "p90_latency": 8000,
                        "p50_latency": 500,
                        "requests_count": 34,
                        "threshold": 7000,
                        "alert_state": "ACTIVATED"
                    },
                    "field": "flows"
                }
            ]
        }
    ],
    "object": "whatsapp_business_account"
}

ENDPOINT_AVAILABILITY

The event field is "ENDPOINT_AVAILABILITY".

Example

Complete ENDPOINT_AVAILABILITY example:

{
    "entry": [
        {
            "id": "106181168862417",
            "time": 1674160476,
            "changes": [
                {
                    "value": {
                        "event": "ENDPOINT_AVAILABILITY",
                        "message": "The flow endpoint availability has breached the 90% threshold in the last 10 minutes. Users will be unable to open or use the flow.",
                        "flow_id": "12345678",
                        "alert_state": "ACTIVATED",
                        "availability": 75,
                        "threshold": 90
                    },
                    "field": "flows"
                }
            ]
        }
    ],
    "object": "whatsapp_business_account"
}

Flow version freeze or expiry warning

Sent when a Flow version is about to be frozen or to expire, so you can migrate to the recommended version before you lose the ability to publish or send the Flow. There are two cases:

On Flow creation, if a version in use is about to freeze: a FLOW_STATUS_CHANGE event that also includes a warning field.
When you send a Flow whose version is about to expire: a dedicated FLOW_VERSION_EXPIRY_WARNING event. WhatsApp aims to send only one of these per affected Flow.

Example

Complete Flow version freeze or expiry warning example:

Freeze warning on Flow creation

{
    "entry": [
        {
            "id": "644600416743275",
            "time": 1684969340,
            "changes": [
                {
                    "value": {
                        "event": "FLOW_STATUS_CHANGE",
                        "message": "Flow Webhook 3 has been created with DRAFT status",
                        "flow_id": "6627390910605886",
                        "new_status": "DRAFT",
                        "warning": "Your current Flow version will freeze in 21 days. You won't be able to send the Flow after it expires. Please migrate to the recommended version as soon as possible."
                    },
                    "field": "flows"
                }
            ]
        }
    ],
    "object": "whatsapp_business_account"
}

Version expiry warning

{
    "entry": [
        {
            "id": "644600416743275",
            "time": 1684969340,
            "changes": [
                {
                    "value": {
                        "event": "FLOW_VERSION_EXPIRY_WARNING",
                        "warning": "Your current Flow version will freeze in 21 days. You won't be able to send the Flow after it expires. Please migrate to the recommended version as soon as possible.",
                        "flow_id": "6627390910605886"
                    },
                    "field": "flows"
                }
            ]
        }
    ],
    "object": "whatsapp_business_account"
}