Configurar webhooks

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 empezar

Guarda tu clave de API de YCloud en YCLOUD_API_KEY.
Implementa 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 tipos de eventos.
Guarda el secret devuelto del endpoint.
YCloud envía una solicitud de evento a tu endpoint.
Verifica YCloud-Signature antes de confiar en la solicitud.
Devuelve una respuesta 2xx de inmediato.
Procesa el evento de forma idempotente, ya que la entrega puede repetirse.

Solicitud

Crea un endpoint con POST /webhookEndpoints.

Campos de la solicitud

Campo	Obligatorio	Descripción
`url`	Sí	URL HTTPS pública que recibe solicitudes de eventos. Máximo 500 caracteres.
`enabledEvents`	Sí	Tipos de eventos entregados a este endpoint.
`eventProperties`	Condicional	Propiedades incluidas para los tipos de eventos seleccionados. Obligatorio para `contact.attributes_changed`.
`description`	No	Descripción del endpoint. Máximo 400 caracteres.
`status`	No	Estado inicial del endpoint.

Ejemplo de solicitud

curl --request POST https://api.ycloud.com/v2/webhookEndpoints \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/webhooks/ycloud",
    "enabledEvents": [
      "whatsapp.inbound_message.received",
      "whatsapp.message.updated",
      "sms.message.updated"
    ],
    "description": "Production messaging events"
}'

Suscribirse a eventos de eco y de transferencia

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 modificar un endpoint existente, conserva las suscripciones a eventos que aún necesites.

curl --request POST https://api.ycloud.com/v2/webhookEndpoints \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/webhooks/ycloud",
    "enabledEvents": [
      "whatsapp.echo_message.created",
      "whatsapp.echo_message.updated",
      "whatsapp.meta_business_agent.handover.updated",
      "whatsapp.inbound_message.received"
    ],
    "description": "API Agent echo and handover events"
  }'

Los dos tipos de eventos de eco contienen una carga útil estándar con forma de mensaje whatsappMessage. El evento de transferencia contiene 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 eventos de eco y de transferencia para ver definiciones de campos, ejemplos, orden y límites de correlación de transferencias.

Suscribirse a eventos de mensajes de Messenger

Tipo de evento	Carga útil	Cuándo ocurre
`messenger.inbound_message.received`	`messengerInboundMessage`	Un cliente envía un mensaje de texto normal.
`messenger.inbound_message.updated`	`messengerInboundMessage`	Un cliente edita un mensaje de texto entrante almacenado.
`messenger.message.updated`	`messengerMessage`	Un resultado de envío saliente o un recibo de mensaje coincidente está disponible.
`messenger.message_reaction.updated`	`messengerMessageReaction`	Un cliente reacciona a un mensaje o retira su reacción.

Incluye los nombres de eventos que necesites en enabledEvents al crear o actualizar un endpoint. Por ejemplo, suscríbete a los cuatro con:

{
  "url": "https://example.com/webhooks/ycloud",
  "enabledEvents": [
    "messenger.inbound_message.received",
    "messenger.inbound_message.updated",
    "messenger.message.updated",
    "messenger.message_reaction.updated"
  ]
}

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 el createTime del mensaje permanecen sin cambios; el createTime del envoltorio del evento es la hora de la edición. Los mensajes no editados omiten los campos de edición. Solo se actualiza un mensaje entrante existente. Las ediciones anteriores se ignoran; los mensajes faltantes y las ediciones históricas no se reconstruyen. Correlaciona las actualizaciones mediante el ID del mensaje y usa el conteo acumulativo para evitar aplicar un texto anterior sobre una versión más reciente. Los reintentos del origen pueden generar 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 modifica 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 local de mensaje ni incluye un ID de mensaje local. El createTime del evento conserva la hora de interacción de origen. Los reintentos de entrega a un cliente conservan su id y carga útil de evento. El procesamiento de retrollamadas de origen puede generar otro ID de evento para una interacción repetida; no trates los ID de evento como identidades de reacciones o de mensajes. Consulta los ejemplos de carga útil de reacciones 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

{
  "id": "WEBHOOK_ENDPOINT_ID",
  "url": "https://example.com/webhooks/ycloud",
  "enabledEvents": [
    "whatsapp.inbound_message.received",
    "whatsapp.message.updated",
    "sms.message.updated"
  ],
  "description": "Production messaging events",
  "status": "active",
  "secret": "whsec_REPLACE_WITH_RETURNED_SECRET",
  "createTime": "2026-07-16T12:00:00.000Z",
  "updateTime": "2026-07-16T12:00:00.000Z"
}

Campos de la respuesta

Campo	Descripción
`id`	ID del endpoint de Webhook utilizado para obtener, actualizar, eliminar o rotar el secreto del endpoint.
`url`	URL de destino para la entrega de eventos.
`enabledEvents`	Tipos de eventos habilitados actualmente.
`status`	Estado actual del endpoint.
`secret`	Secreto utilizado para verificar `YCloud-Signature`. Guárdalo de forma segura.
`createTime`, `updateTime`	Marcas de tiempo del endpoint en formato RFC 3339.

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 e createTime, además de una carga útil específica del tipo. Tu controlador debe:

Leer el cuerpo sin procesar de la solicitud.
Validar el encabezado YCloud-Signature con el secreto del endpoint antes de confiar en la carga útil.
Devolver una respuesta exitosa 2xx a la brevedad.
Mover el procesamiento lento a una cola.
Hacer que el procesamiento de eventos sea idempotente para que la entrega repetida no repita acciones de negocio.

No analices ni modifiques el cuerpo de la solicitud antes de la validación de la firma. Usa exactamente los bytes sin procesar recibidos por tu servidor.

Respuesta del receptor

Devuelve una respuesta HTTP 2xx exitosa en cuanto se acepten la firma y la solicitud. El cuerpo de la respuesta puede estar vacío.

HTTP/1.1 204 No Content

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 id del evento.

Ejemplos comunes de carga útil

Despliega un evento para inspeccionar su ejemplo completo de carga útil. Estos ejemplos provienen de la especificación de Webhook de OpenAPI. Consulta todos los ejemplos de cargas útiles de Webhook para cada tipo de evento admitido.

Evento de atributos de contacto cambiados

Ejemplo de carga útil cuando se modifican los atributos de un contacto

{
  "id": "evt_1234567890",
  "type": "contact.attributes_changed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactAttributesChanged": {
    "id": "1824266594102064128",
    "updateTime": "2024-01-01T12:00:00.000Z",
    "changedAttributes": {
      "nickName": {
        "oldValue": "John Doe",
        "newValue": "Johnny Doe"
      },
      "email": {
        "oldValue": "john.doe@example.com",
        "newValue": "johnny.doe@example.com"
      },
      "tags": {
        "oldValue": [
          "premium",
          "newsletter"
        ],
        "newValue": [
          "premium",
          "newsletter",
          "vip"
        ],
        "extra": [
          {
            "action": "ADDED",
            "id": "686dd294334be8606a5bf312",
            "value": "vip"
          }
        ]
      }
    }
  }
}

Evento de contacto creado

Ejemplo de carga útil cuando se crea un nuevo contacto

{
  "id": "evt_2345678901",
  "type": "contact.created",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactCreated": {
    "id": "1824266594102064128",
    "nickName": "John Doe",
    "realName": "John Smith",
    "phoneNumber": "+16315551111",
    "countryCode": "US",
    "countryName": "United States",
    "email": "john.doe@example.com",
    "sourceType": "api",
    "sourceId": "import_batch_123",
    "sourceUrl": "https://example.com/signup",
    "lastSeen": "2024-01-01T11:59:00.000Z",
    "lastConnectedNumber": "+16315552222",
    "ownerEmail": "owner@example.com",
    "tags": [
      "premium",
      "newsletter"
    ],
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-01T12:00:00.000Z",
    "blocked": false,
    "customAttributes": {
      "attr1": "value1",
      "attr2": "value2",
      "attr3": 123
    }
  }
}

Evento de contacto eliminado

Ejemplo de carga útil cuando se elimina un contacto

{
  "id": "evt_3456789012",
  "type": "contact.deleted",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactDeleted": {
    "id": "1824266594102064128",
    "nickName": "John Doe",
    "phoneNumber": "+16315551111",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

Evento de cancelación de suscripción por parte del cliente

Ejemplo de carga útil cuando un cliente cancela la suscripción

{
  "id": "evt_3456789012",
  "type": "contact.unsubscribe.created",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "unsubscriberChanged": {
    "phoneNumber": "+16315551111",
    "source": "Whatsapp",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

El cliente reanuda la suscripción

Ejemplo de carga útil cuando un cliente reanuda la suscripción

{
  "id": "evt_3456789012",
  "type": "contact.unsubscribe.deleted",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "unsubscriberChanged": {
    "phoneNumber": "+16315551111",
    "source": "Whatsapp",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

Evento de plantilla de WhatsApp archivada

Ejemplo de carga útil cuando se archiva una plantilla de WhatsApp

{
  "id": "evt_template_archived_123",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappTemplate": {
    "id": "template-id",
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "sample_whatsapp_template",
    "language": "en",
    "category": "MARKETING",
    "status": "ARCHIVED",
    "statusUpdateEvent": "ARCHIVED",
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

Evento de plantilla de WhatsApp desarchivada

Ejemplo de carga útil 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.

{
  "id": "evt_template_unarchived_123",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappTemplate": {
    "id": "template-id",
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "sample_whatsapp_template",
    "language": "en",
    "category": "MARKETING",
    "status": "APPROVED",
    "statusUpdateEvent": "UNARCHIVED",
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

Evento de llamada de WhatsApp conectada

Ejemplo de carga útil cuando se conecta una llamada de WhatsApp

{
  "id": "evt_call_connect_123",
  "type": "whatsapp.call.connect",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "callingConnect": {
    "id": "6757b723960b25543b9ecc66",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABIYIEF",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "dialTime": 1733826430000,
    "sdpType": "offer",
    "sdp": "v=0\r\no=- 1732169627243 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE audio\r\na=msid-semantic: WMS af3b01e3-eb42-4244-812e-db903c062ae7\r\na=ice-lite\r\nm=audio 3480 UDP/TLS/RTP/SAVPF 111 126\r\nc=IN IP4 31.13.87.130\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:785588535 1 udp 2122260223 31.13.87.130 3480 typ host generation 0 network-cost 50\r\na=candidate:1906600321 1 udp 2122262783 2a03:2880:f217:d0:face:b00c:0:699c 3480 typ host generation 0 network-cost 50\r\na=ice-ufrag:CvRXRnInnWhQzLIE\r\na=ice-pwd:HGXUGAFI8wK6seuVknBT2Q==\r\na=fingerprint:sha-256 FB:56:A1:C5:37:35:6C:5C:1B:05:23:B0:DD:BB:2E:C9:5F:E4:70:61:7B:D9:1D:09:84:76:46:23:12:38:B7:01\r\na=setup:actpass\r\na=mid:audio\r\na=sendrecv\r\na=msid:af3b01e3-eb42-4244-812e-db903c062ae7 WhatsAppTrack1\r\na=rtcp-mux\r\na=rtpmap:111 opus/48000/2\r\na=rtcp-fb:111 transport-cc\r\na=fmtp:111 maxaveragebitrate=20000;maxplaybackrate=16000;minptime=20;sprop-maxcapturerate=16000;useinbandfec=1\r\na=rtpmap:126 telephone-event/8000\r\na=maxptime:20\r\na=ptime:20\r\na=ssrc:659928310 cname:WhatsAppAudioStream1\r\n"
  }
}

Evento de llamada de WhatsApp finalizada

Ejemplo de carga útil cuando finaliza una llamada de WhatsApp

{
  "id": "evt_6757b889a5a42d369ef48481",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2024-12-10T03:42:01.822Z",
  "callingTerminate": {
    "id": "6757b889960b25543b9ecc67",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABIYIEFENjB",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "startTime": 1733734738000,
    "endTime": 1733734771000,
    "duration": 33,
    "status": "COMPLETED"
  }
}

Evento de estado de llamada de WhatsApp actualizado

Ejemplo de carga útil cuando se actualiza el estado de una llamada de WhatsApp

{
  "id": "evt_676e5ab57a9cb742d02d7646",
  "type": "whatsapp.call.status.updated",
  "apiVersion": "v2",
  "createTime": "2024-12-27T07:41:28.422Z",
  "callingStatusUpdated": {
    "wabaId": "188234691048809",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "status": "RINGING",
    "recipientPhone": "+6281361905133"
  }
}

Consulta Cargas útiles de eventos de Webhook para ver el esquema completo de Event y la referencia interactiva de cargas útiles.

Rotar el secreto del endpoint

Rota un secreto si queda expuesto o como parte de tu política de seguridad:

curl --request POST \
  https://api.ycloud.com/v2/webhookEndpoints/WEBHOOK_ENDPOINT_ID/rotateSecret \
  --header "X-API-Key: $YCLOUD_API_KEY"

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. Monitorea los fallos de webhook y el estado del endpoint.

Para obtener el código de verificación de firmas, los intervalos de reintento y la implementación del receptor, consulta Implementar un receptor de webhook.

Primeros pasos

Guías

Endpoints

Webhooks

Qué es

Antes de empezar

Cómo funciona

Solicitud

Campos de la solicitud

Ejemplo de solicitud

Suscribirse a eventos de eco y de transferencia

Suscribirse a eventos de mensajes de Messenger

Respuesta

Ejemplo de respuesta

Campos de la respuesta

Recibir eventos

Solicitud de evento

Respuesta del receptor

Ejemplos comunes de carga útil

Rotar el secreto del endpoint

​Qué es

​Antes de empezar

​Cómo funciona

​Solicitud

​Campos de la solicitud

​Ejemplo de solicitud

​Suscribirse a eventos de eco y de transferencia

​Suscribirse a eventos de mensajes de Messenger

​Respuesta

​Ejemplo de respuesta

​Campos de la respuesta

​Recibir eventos

​Solicitud de evento

​Respuesta del receptor

​Ejemplos comunes de carga útil

​Rotar el secreto del endpoint

Qué es

Antes de empezar

Cómo funciona

Solicitud

Campos de la solicitud

Ejemplo de solicitud

Suscribirse a eventos de eco y de transferencia

Suscribirse a eventos de mensajes de Messenger

Respuesta

Ejemplo de respuesta

Campos de la respuesta

Recibir eventos

Solicitud de evento

Respuesta del receptor

Ejemplos comunes de carga útil

Rotar el secreto del endpoint