Ejemplos de Webhook para cuenta y número de teléfono de WhatsApp

Para consultar el catálogo exhaustivo basado en el esquema, consulta todos los ejemplos.

Qué es

Gestiona eventos de revisión, actualización y eliminación de cuentas comerciales, además de eliminaciones de números de teléfono, revisiones del nombre para mostrar, calidad y actualizaciones de Business Username. Enruta cada carga útil según su type exacto: los eventos de cuenta usan whatsappBusinessAccount, mientras que los eventos de número de teléfono usan whatsappPhoneNumber.

Antes de comenzar

Crea un endpoint HTTPS público en tu aplicación.
Configura un endpoint de Webhook de YCloud para los tipos de eventos que necesites.
Guarda el secreto de firma del endpoint de forma segura.
Haz que el procesamiento de eventos sea idempotente.

Cómo funciona

YCloud envía una solicitud HTTP POST cuando ocurre el evento. Verifica la firma, registra el evento de forma duradera, devuelve una respuesta 2xx y procesa las tareas lentas de forma asíncrona.

Solicitud

Los escenarios a continuación muestran solicitudes entregadas a tu URL de Webhook. Trata el id del evento como el identificador de entrega y usa type para enrutar la carga útil.

Respuesta

Devuelve un estado 2xx tras aceptar el evento.

HTTP/1.1 200 OK

Para la configuración del endpoint, la validación de la firma y el comportamiento de reintentos, consulta Configurar webhooks.

Eliminación de la cuenta

Usa whatsapp.business_account.deleted para gestionar un evento de eliminación de una cuenta de WhatsApp Business. Lee whatsappBusinessAccount.id para identificar la WABA afectada.

Solicitud

{
  "id": "evt_business_account_deleted_123",
  "type": "whatsapp.business_account.deleted",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "whatsapp-business-account-id",
    "name": "Example business",
    "removedReason": "ACCOUNT_DISCONNECTED",
    "removedInitiatedBy": "USER",
    "removedTime": "2026-05-26T12:00:00.000Z"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Los campos de eliminación aparecen directamente dentro de whatsappBusinessAccount cuando están disponibles.

Campo	Significado
`id`	El ID de la cuenta de WhatsApp Business afectada.
`removedReason`	El motivo de eliminación original. Consulta los valores conocidos más abajo.
`removedInitiatedBy`	`USER` para eliminación iniciada por el usuario de WhatsApp, o `SYSTEM` para eliminación iniciada por Meta.
`removedTime`	La hora en que YCloud recibió el evento de eliminación, en formato RFC 3339.

Los valores conocidos de removedReason incluyen:

Valor	Significado
`ACCOUNT_DISCONNECTED`	La cuenta se desconectó debido a una sanción o porque la cuenta de WhatsApp se eliminó explícitamente.
`BUSINESS_DOWNGRADE`	El número de teléfono se registró con la aplicación de consumo de WhatsApp.
`CHANGE_NUMBER`	Se cambió el número de teléfono de WhatsApp.
`COMPANION_INACTIVITY`	Un dispositivo complementario estuvo inactivo durante aproximadamente 30 días.
`PRIMARY_INACTIVITY`	Un dispositivo principal estuvo inactivo durante aproximadamente 30 días.
`USER_RE_REGISTERED`	WhatsApp se volvió a registrar en un dispositivo nuevo.

Conserva los valores de motivo e iniciador desconocidos. Deduplica las entregas por el id del evento y tolera los campos de eliminación omitidos.

Authentication-International Rate Eligibility

A partir del 1 de junio de 2024, introduciremos una nueva tarifa de autenticación internacional. Esta tarifa se aplicará en los siguientes países:

1 de junio de 2024 – Indonesia (código de llamada de país +62, código de país ID)
1 de julio de 2024 – India (código de llamada de país +91, código de país IN)

Para más información, consulta Authentication-International Rate Eligibility . Se activará un Webhook whatsapp.business_account.updated si tu empresa se considera elegible para tarifas internacionales. El Webhook incluirá las horas de inicio para cada país que tenga una tarifa de autenticación internacional.

Solicitud

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "AUTH_INTL_PRICE_ELIGIBILITY_UPDATE",
    "authIntlRateEligibilityCountries": [
      {
        "countryCode": "IN",
        "startTime": "2024-07-01T00:00:00.000Z"
      },
      {
        "countryCode": "ID",
        "startTime": "2024-07-01T00:00:00.000Z"
      }
    ]
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Si un mensaje se factura a la tarifa de autenticación internacional, el campo whatsappMessage.pricingCategory en los webhooks whatsapp.message.updated se establecerá en authentication_international. Aquí tienes un ejemplo:

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2024-07-01T00:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "wabaId": "whatsapp-business-account-id",
    "from": "+447901614024",
    "to": "+447901614024",
    "status": "sent",
    "type": "template",
    "template": {
      "name": "login_otp",
      "language": {
        "code": "862031",
        "policy": "deterministic"
      }
    },
    "conversation": {
      "id": "8078ed05301c40a08d3d1845c94ca18b",
      "originType": "authentication",
      "expireTime": "2024-07-01T00:00:00.000Z"
    },
    "pricingCategory": "authentication_international",
    "totalPrice": 0.085,
    "currency": "USD",
    "sendTime": "2024-07-01T00:00:00.000Z"
  }
}

Explicación

Enruta el evento mediante type, deduplícalo mediante id y traslada el trabajo lento o propenso a errores a un procesador asíncrono.

Primary Business Location Update

Tu ubicación comercial principal es el país donde tiene su sede tu empresa. Aparecerá en el Business Manager bajo el campo Primary Business Location a partir del 1 de mayo de 2024. Si Meta puede determinar el país donde tiene su sede tu empresa, activaremos un Webhook whatsapp.business_account.updated con el código de dos dígitos del país. Aquí tienes un ejemplo:

Solicitud

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE",
    "primaryBusinessLocation": "US"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Enruta el evento mediante type, deduplícalo mediante id y traslada el trabajo lento o propenso a errores a un procesador asíncrono.

Actualización del límite de registro de números de teléfono

Meta envía una actualización de la capacidad comercial de una WABA cuando cambia el límite de registro de números de teléfono de la WABA o del Business Portfolio correspondiente. YCloud lo entrega como whatsapp.business_account.updated con updateEvent=BUSINESS_CAPABILITY_UPDATE. El webhook es a nivel de WABA: whatsappBusinessAccount.id es el ID de WABA de la entrada del webhook de Meta. Meta actualmente informa maxPhoneNumbersPerBusiness y maxPhoneNumbersPerWaba en actualizaciones independientes. No los trates como mutuamente excluyentes: procesa cada campo por separado y acepta ambos si una actualización futura los incluye juntos. Un valor de 0 es válido. Aquí tienes un ejemplo de una actualización de límite de números de teléfono de WABA:

Solicitud

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-23T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "BUSINESS_CAPABILITY_UPDATE",
    "maxPhoneNumbersPerWaba": 25
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Enruta el evento mediante type, deduplícalo mediante id y actualiza únicamente el campo de límite incluido en la carga útil.

Infracción de la cuenta

Cuando recibas un evento whatsapp.business_account.updated con whatsappBusinessAccount.updateEvent configurado como ACCOUNT_VIOLATION, inspecciona whatsappBusinessAccount.violationType para identificar la infracción de política notificada. Consulta Policy enforcement violations de Meta para conocer los tipos y descripciones de las infracciones. Meta puede actualizar esta lista con el tiempo. Aquí tienes un ejemplo:

Solicitud

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "ACCOUNT_VIOLATION",
    "violationType": "SCAM"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Enruta el evento mediante type, deduplícalo mediante id y traslada el trabajo lento o propenso a errores a un procesador asíncrono.

Restricción de la cuenta

Si las cuentas comerciales infringen repetidamente las Condiciones del servicio de WhatsApp Business o categorías de políticas de alto riesgo, como el envío de spam, contenido para adultos, venta de alcohol y tabaco, drogas, juegos de azar y suplementos no seguros, pueden empezar a sufrir restricciones de mensajería que aumentan gradualmente de duración. Para Utility Direct Send, consulta Direct Send notifications para ver una carga útil de ACCOUNT_RESTRICTION en YCloud. Consulta Webhook for account restriction de Meta para conocer los tipos de infracciones y los detalles de las restricciones específicos de Direct Send. Aquí tienes un ejemplo:

Solicitud

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "ACCOUNT_RESTRICTION",
    "restrictions": [
      {
        "restrictionType": "RESTRICTED_ADD_PHONE_NUMBER_ACTION",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
      {
        "restrictionType": "RESTRICTED_BIZ_INITIATED_MESSAGING",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
      {
        "restrictionType": "RESTRICTED_CUSTOMER_INITIATED_MESSAGING",
        "expiration": "2024-09-01T12:00:00.000Z"
      }
    ]
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Enruta el evento mediante type, deduplícalo mediante id y traslada el trabajo lento o propenso a errores a un procesador asíncrono.

Restricción de Utility Direct Send

Recibes whatsapp.business_account.updated cuando Meta restringe Utility Direct Send tras un uso indebido reiterado de la categoría. Este ejemplo muestra una restricción de siete días.

Solicitud

{
  "id": "evt_direct_send_restriction_123",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-17T08:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "whatsapp-business-account-id",
    "name": "Example business",
    "updateEvent": "ACCOUNT_RESTRICTION",
    "violationType": "DIRECT_SEND_UTILITY_CATEGORY_ABUSE_STRIKE_1",
    "restrictions": [
      {
        "restrictionType": "RESTRICTED_DIRECT_SEND_UTILITY_TEMPLATES",
        "expiration": "2026-09-24T08:00:00.000Z"
      }
    ]
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Utiliza whatsappBusinessAccount.id para identificar la WABA afectada y pausar su flujo de trabajo de Utility Direct Send. Lee violationType para conocer el motivo, restrictions[].restrictionType para la funcionalidad afectada y restrictions[].expiration para la fecha de vencimiento si se proporciona. La revisión correcta de una plantilla no levanta de manera automática una restricción a nivel de cuenta. Consulta Direct Send restrictions and notifications.

Cuenta desactivada

Las cuentas de WhatsApp Business pueden desactivarse si la empresa no realiza cambios tras múltiples advertencias y bloqueos o límites de funciones. Aquí tienes un ejemplo:

Solicitud

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "DISABLED_UPDATE",
    "banDate": "September 19, 2024",
    "banState": "DISABLE"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Enruta el evento mediante type, deduplícalo mediante id y traslada el trabajo lento o propenso a errores a un procesador asíncrono.

Restablecimiento de la cuenta

Puedes apelar la decisión de bloqueo de la cuenta de WhatsApp Business para restablecerla. Una vez aprobada, el estado de revisión de la cuenta cambia a APPROVED. Aquí tienes un ejemplo:

Solicitud

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "DISABLED_UPDATE",
    "banState": "REINSTATE",
    "banDate": "December 27, 2024",
    "accountReviewStatus": "APPROVED"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Enruta el evento mediante type, deduplícalo mediante id y traslada el trabajo lento o propenso a errores a un procesador asíncrono.

Revisión de la cuenta comercial

Utiliza whatsapp.business_account.reviewed cuando se haya revisado una cuenta de WhatsApp Business.

Solicitud

{
  "id": "evt_example_whatsapp_business_account_reviewed",
  "type": "whatsapp.business_account.reviewed",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "whatsapp-business-account-id",
    "decision": "APPROVED",
    "accountReviewStatus": "APPROVED"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Identifica la WABA con id. Lee decision para conocer la decisión de revisión (APPROVED o REJECTED) y accountReviewStatus para el estado de revisión de la cuenta si se proporciona. No enrutes este evento como whatsapp.business_account.updated.

Eliminación de número de teléfono

Utiliza whatsapp.phone_number.deleted cuando se elimine un número de teléfono comercial de WhatsApp.

Solicitud

{
  "id": "evt_example_whatsapp_phone_number_deleted",
  "type": "whatsapp.phone_number.deleted",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "wabaId": "whatsapp-business-account-id"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Utiliza whatsappPhoneNumber.id para identificar el número de teléfono eliminado y wabaId para asociarlo con su cuenta. Este es un evento de número de teléfono; no lo trates como la eliminación de toda la WABA.

Revisión del nombre visible del número de teléfono

Utiliza whatsapp.phone_number.name_updated cuando se apruebe o rechace el nombre visible de un número de teléfono comercial.

Solicitud

{
  "id": "evt_example_whatsapp_phone_number_name_updated",
  "type": "whatsapp.phone_number.name_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "wabaId": "whatsapp-business-account-id",
    "verifiedName": "Example business",
    "requestedVerifiedName": "Example business",
    "decision": "APPROVED",
    "nameStatus": "APPROVED",
    "newNameStatus": "APPROVED"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Lee decision y los campos de estado del nombre proporcionados. newNameStatus describe la nueva solicitud de nombre visible, requestedVerifiedName identifica el último nombre solicitado y rejectionReason describe un rechazo cuando esté presente. La revisión del nombre visible es independiente de una actualización del nombre de usuario de la empresa.

Actualización de la calidad del número de teléfono

Utiliza whatsapp.phone_number.quality_updated para cambios en el estado relacionado con la calidad de un número de teléfono comercial.

Solicitud

{
  "id": "evt_phone_number_quality_updated_123",
  "type": "whatsapp.phone_number.quality_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "qualityRating": "GREEN",
    "messagingLimit": "TIER_1K",
    "whatsappBusinessManagerMessagingLimit": "TIER_2K",
    "qualityUpdateEvent": "ONBOARDING"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Lee qualityRating (GREEN, YELLOW o RED) y qualityUpdateEvent para entender la actualización. messagingLimit es el nivel del número de teléfono; whatsappBusinessManagerMessagingLimit es el límite de la cartera comercial propietaria. Mantén estos campos separados y actualiza únicamente los valores proporcionados en el evento.

Business Username activado

Usa whatsapp.phone_number.business_username_updated para sincronizar el Business Username de un número de teléfono.

Solicitud

{
  "id": "evt_business_username_updated_123",
  "type": "whatsapp.phone_number.business_username_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "businessUsername": "acme.support",
    "businessUsernameStatus": "active",
    "businessUsernameUpdatedAt": "2026-05-26T12:00:00.000Z"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

businessUsername es el nombre de usuario activo sin un @ inicial. Lee businessUsernameStatus y businessUsernameUpdatedAt junto con el id del número de teléfono. No confundas este valor con el nombre para mostrar verificado.

Solicitud de Business Username reservada

Un Business Username activo puede seguir utilizándose mientras se reserva una solicitud de reemplazo.

Solicitud

{
  "id": "evt_business_username_pending_123",
  "type": "whatsapp.phone_number.business_username_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:30:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+16315551111",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "businessUsername": "acme.support",
    "businessUsernameStatus": "reserved",
    "requestedBusinessUsername": "acme.help",
    "businessUsernameUpdatedAt": "2026-05-26T12:30:00.000Z"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

En este ejemplo, businessUsername permanece como acme.support mientras que requestedBusinessUsername es acme.help. El estado reserved describe la solicitud pendiente, no la activación del reemplazo. Acepta el valor heredado pending_review al leer eventos anteriores; las nuevas operaciones de escritura usan reserved.

​Qué es

​Antes de comenzar

​Cómo funciona

​Solicitud

​Respuesta

​Eliminación de la cuenta

​Solicitud

​Respuesta

​Explicación

​Authentication-International Rate Eligibility

​Solicitud

​Respuesta

​Explicación

​Primary Business Location Update

​Solicitud

​Respuesta

​Explicación

​Actualización del límite de registro de números de teléfono

​Solicitud

​Respuesta

​Explicación

​Infracción de la cuenta

​Solicitud

​Respuesta

​Explicación

​Restricción de la cuenta

​Solicitud

​Respuesta

​Explicación

​Restricción de Utility Direct Send

​Solicitud

​Respuesta

​Explicación

​Cuenta desactivada

​Solicitud

​Respuesta

​Explicación

​Restablecimiento de la cuenta

​Solicitud

​Respuesta

​Explicación

​Revisión de la cuenta comercial

​Solicitud

​Respuesta

​Explicación

​Eliminación de número de teléfono

​Solicitud

​Respuesta

​Explicación

​Revisión del nombre visible del número de teléfono

​Solicitud

​Respuesta

​Explicación

​Actualización de la calidad del número de teléfono

​Solicitud

​Respuesta

​Explicación

​Business Username activado

​Solicitud

​Respuesta

​Explicación

​Solicitud de Business Username reservada

​Solicitud

​Respuesta

​Explicación

Qué es

Antes de comenzar

Cómo funciona

Solicitud

Respuesta

Eliminación de la cuenta

Solicitud

Respuesta

Explicación

Authentication-International Rate Eligibility

Solicitud

Respuesta

Explicación

Primary Business Location Update

Solicitud

Respuesta

Explicación

Actualización del límite de registro de números de teléfono

Solicitud

Respuesta

Explicación

Infracción de la cuenta

Solicitud

Respuesta

Explicación

Restricción de la cuenta

Solicitud

Respuesta

Explicación

Restricción de Utility Direct Send

Solicitud

Respuesta

Explicación

Cuenta desactivada

Solicitud

Respuesta

Explicación

Restablecimiento de la cuenta

Solicitud

Respuesta

Explicación

Revisión de la cuenta comercial

Solicitud

Respuesta

Explicación

Eliminación de número de teléfono

Solicitud

Respuesta

Explicación

Revisión del nombre visible del número de teléfono

Solicitud

Respuesta

Explicación

Actualización de la calidad del número de teléfono

Solicitud

Respuesta

Explicación

Business Username activado

Solicitud

Respuesta

Explicación

Solicitud de Business Username reservada

Solicitud

Respuesta

Explicación