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
- Crea un endpoint de Webhook y suscríbelo a los tipos de eventos.
- Guarda el
secretdel endpoint devuelto. - YCloud envía una solicitud de evento a tu endpoint.
- Verifica
YCloud-Signatureantes de confiar en la solicitud. - Devuelve una respuesta
2xxcon prontitud. - Procesa el evento de forma idempotente, ya que la entrega puede repetirse.
Solicitud
Crea un endpoint conPOST /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.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:
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 susecret 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 laurl 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:
- Leer el cuerpo sin procesar de la solicitud.
- Validar el encabezado
YCloud-Signaturecon el secreto del endpoint antes de confiar en la carga útil. - Devolver una respuesta
2xxcorrecta de inmediato. - Mover el procesamiento lento a una cola.
- Hacer que el procesamiento de eventos sea idempotente para que las entregas repetidas no reiteren acciones comerciales.
Respuesta del receptor
Devuelve una respuesta HTTP2xx correcta tan pronto como la firma y la solicitud sean aceptadas. El cuerpo de la respuesta puede estar vacío.
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.Evento de atributos de contacto modificados
Evento de atributos de contacto modificados
Carga útil de ejemplo cuando se modifican los atributos de un contacto
Evento de contacto creado
Evento de contacto creado
Carga útil de ejemplo cuando se crea un nuevo contacto
Evento de contacto eliminado
Evento de contacto eliminado
Carga útil de ejemplo cuando se elimina un contacto
Evento de cliente que cancela la suscripción
Evento de cliente que cancela la suscripción
Carga útil de ejemplo cuando un cliente cancela la suscripción
Cliente reanuda la suscripción
Cliente reanuda la suscripción
Carga útil de ejemplo cuando un cliente reanuda la suscripción
Evento de plantilla de WhatsApp archivada
Evento de plantilla de WhatsApp archivada
Carga útil de ejemplo cuando se archiva una plantilla de WhatsApp
Evento de plantilla de WhatsApp desarchivada
Evento de plantilla de WhatsApp desarchivada
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.
Evento de llamada de WhatsApp conectada
Evento de llamada de WhatsApp conectada
Carga útil de ejemplo cuando se conecta una llamada de WhatsApp
Evento de llamada de WhatsApp finalizada
Evento de llamada de WhatsApp finalizada
Carga útil de ejemplo cuando finaliza una llamada de WhatsApp
Evento de estado de llamada de WhatsApp actualizado
Evento de estado de llamada de WhatsApp actualizado
Carga útil de ejemplo cuando se actualiza el estado de una llamada de WhatsApp
Rotar el secreto del endpoint
Rota un secreto si queda expuesto o como parte de tu política de seguridad: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.
