Saltar al contenido principal

Qué es

Los webhooks son solicitudes HTTPS que YCloud envía a tu aplicación cuando cambian la entrega de mensajes, los mensajes entrantes, los contactos, las plantillas, las llamadas y otros recursos.

Antes de comenzar

  • Guarda tu clave de API de YCloud en YCLOUD_API_KEY.
  • Despliega un endpoint HTTPS accesible públicamente.
  • Conserva el cuerpo sin procesar de la solicitud para la verificación de firmas.
  • Decide qué tipos de eventos necesita tu aplicación.

Cómo funciona

  1. Crea un endpoint de Webhook y suscríbelo a los tipos de eventos.
  2. Guarda el secret del endpoint devuelto.
  3. YCloud envía una solicitud de evento a tu endpoint.
  4. Verifica YCloud-Signature antes de confiar en la solicitud.
  5. Devuelve una respuesta 2xx con prontitud.
  6. Procesa el evento de forma idempotente, ya que la entrega puede repetirse.

Solicitud

Crea un endpoint con POST /webhookEndpoints.

Campos de la solicitud

Ejemplo de solicitud

Suscribirse a eventos de eco y traspaso

Para los Agentes incorporados a través de la API REST pública, crea un endpoint con las siguientes suscripciones. Los Agentes creados en la consola no emiten estos tres eventos. Para cambiar un endpoint existente, conserva las suscripciones a eventos que aún necesites.
Los dos tipos de eventos de eco llevan una carga útil whatsappMessage estándar con formato de mensaje. El evento de traspaso lleva whatsappMetaBusinessAgent y conserva su información de Agente/control. No utilizan el contrato whatsapp.smb.message.echoes de la aplicación WhatsApp Business. Consulta los detalles de los eventos de eco y traspaso para ver las definiciones de campos, ejemplos, orden y límites de correlación de traspasos.

Suscribirse a eventos de mensajes de Messenger

Incluye los nombres de eventos que necesites en enabledEvents cuando crees o actualices un endpoint. Por ejemplo, suscríbete a los cuatro con:
En el Dashboard, un nuevo endpoint comienza sin eventos seleccionados. Al seleccionar la categoría Messenger , se seleccionan sus eventos disponibles, incluidas las ediciones y las reacciones. Luego puedes deseleccionar eventos individuales. Las suscripciones existentes no incluyen automáticamente los eventos de edición o reacción recién agregados. Conserva las suscripciones que aún necesites al actualizar un endpoint. Una edición conserva el mismo messengerInboundMessage.id y metaMessageId, reemplaza text.body y agrega editCount y editTime. El sendTime y createTime del mensaje permanecen sin cambios; el sobre del evento createTime es la hora de edición. Los mensajes no editados omiten los campos de edición. Solo se actualiza un mensaje entrante existente. Las ediciones más antiguas se ignoran; los mensajes faltantes y las ediciones históricas no se reconstruyen. Correlaciona las actualizaciones por ID de mensaje y utiliza el conteo acumulativo para evitar aplicar un texto más antiguo sobre una versión más nueva. Los reintentos del origen pueden crear otro ID de evento para la misma edición guardada. Consulta el ejemplo de edición entrante. Los eventos de reacción contienen pageId, el psid del cliente que reacciona, el metaMessageId de destino y action (react o unreact). Los campos opcionales reaction y emoji pueden estar ausentes, especialmente para unreact. Una reacción no cambia el estado de entrega de un mensaje. El mensaje de destino puede originarse fuera de la API de YCloud, por lo que el evento no requiere un registro de mensaje local ni incluye un ID de mensaje local. El createTime del evento conserva la hora de interacción de origen. Los reintentos de una entrega al cliente mantienen su id y la carga útil del evento. El procesamiento de callbacks de origen puede generar otro ID de evento para una interacción repetida; no trates los ID de evento como identidades de reacción o de mensaje. Consulta los ejemplos de cargas útiles de reacción para ambas acciones.

Respuesta

La respuesta devuelve el endpoint creado y su secret de firma. Guarda el secreto de forma segura. YCloud lo utiliza para generar firmas de Webhook.

Ejemplo de respuesta

Campos de respuesta

Recibir eventos

Solicitud de evento

YCloud envía un objeto de evento JSON a la url configurada. El evento incluye campos comunes como id, type, apiVersion y createTime, además de una carga útil específica para el tipo. Tu controlador debe:
  1. Leer el cuerpo sin procesar de la solicitud.
  2. Validar el encabezado YCloud-Signature con el secreto del endpoint antes de confiar en la carga útil.
  3. Devolver una respuesta 2xx correcta de inmediato.
  4. Mover el procesamiento lento a una cola.
  5. Hacer que el procesamiento de eventos sea idempotente para que las entregas repetidas no reiteren acciones comerciales.
No analices ni modifiques el cuerpo de la solicitud antes de validar la firma. Usa exactamente los mismos bytes sin procesar que reciba tu servidor.

Respuesta del receptor

Devuelve una respuesta HTTP 2xx correcta tan pronto como la firma y la solicitud sean aceptadas. El cuerpo de la respuesta puede estar vacío.
Mueve el procesamiento comercial lento a una cola. Un tiempo de espera agotado o una respuesta distinta de 2xx puede hacer que YCloud reintente el evento, por lo que debes deduplicar por el id del evento.

Ejemplos habituales de carga útil

Despliega un evento para inspeccionar su carga útil de ejemplo completa. Estos ejemplos provienen de la especificación OpenAPI de webhooks. Consulta todos los ejemplos de carga útil de webhook para ver cada tipo de evento admitido.
Carga útil de ejemplo cuando se modifican los atributos de un contacto
Carga útil de ejemplo cuando se crea un nuevo contacto
Carga útil de ejemplo cuando se elimina un contacto
Carga útil de ejemplo cuando un cliente cancela la suscripción
Carga útil de ejemplo cuando un cliente reanuda la suscripción
Carga útil de ejemplo cuando se archiva una plantilla de WhatsApp
Carga útil de ejemplo cuando se desarchiva una plantilla de WhatsApp. El estado de la plantilla es el estado actual devuelto por Meta y no representa una nueva revisión de aprobación.
Carga útil de ejemplo cuando se conecta una llamada de WhatsApp
Carga útil de ejemplo cuando finaliza una llamada de WhatsApp
Carga útil de ejemplo cuando se actualiza el estado de una llamada de WhatsApp
Consulta la referencia de Webhooks para conocer los desencadenadores de eventos, los campos de carga útil y ver ejemplos.

Rotar el secreto del endpoint

Rota un secreto si queda expuesto o como parte de tu política de seguridad:
Implementa el nuevo secreto en tu receptor inmediatamente después de la rotación.
Un endpoint que falla repetidamente al recibir notificaciones puede pasar al estado pending y dejar de recibir eventos. Supervisa los fallos de webhook y el estado del endpoint.
Para ver el código de verificación de firmas, los intervalos de reintento y la implementación del receptor, consulta Implementar un receptor de webhooks.