Configura notificaciones mediante webhooks

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X. Información

¿Qué es un webhook?

Un webhook define un controlador de devolución de llamada HTTP que un evento activa. Puedes crear webhooks y configurarlos para controlar notificaciones de eventos, como alternativa al uso de plantillas de notificaciones de monetización, como se describe en Configura notificaciones con plantillas de notificaciones.

Para configurar notificaciones mediante webhooks, completa los siguientes pasos mediante la IU de Edge Management o la API de Management y monetización:

  1. Agrega webhooks que definan los controladores de devolución de llamada para los eventos de notificación mediante la IU o la API.
  2. Configura el controlador de devolución de llamada.
  3. Configura la notificación para un plan de tarifas ajustable mediante la IU o la API.

Administra webhooks

Agrega y administra webhooks que definen los controladores de devolución de llamada para los eventos de notificación mediante la IU o la API.

Administra webhooks con la IU

Agrega y administra webhooks que definen los controladores de devolución de llamada para los eventos de notificación mediante la IU, como se describe en las siguientes secciones.

Explora la página de webhooks

Accede a la página de webhooks, como se describe a continuación.

Conexión de integración

Para acceder a la página de webhooks con la IU de Edge, haz lo siguiente:

  1. Accede a apigee.com/edge.
  2. Selecciona Publish > Monetization > Webhooks en la barra de navegación izquierda.

Se mostrará la página de webhooks.

Como se destaca en la figura, la página de webhooks te permite hacer lo siguiente:

Versión clásica de Edge (nube privada)

Para acceder a la página de webhooks con la IU clásica de Edge, sigue estos pasos:

  1. Accede a http://ms-ip:9000, donde ms-ip es la dirección IP o el nombre de DNS del nodo del servidor de administración.

  2. Selecciona Administrador > Webhooks.

Se mostrará la página de webhooks.

La página de webhooks te permite hacer lo siguiente:

Agrega un webhook mediante la IU

Para agregar un webhook con la IU, haz lo siguiente:

  1. Accede a la página de webhooks.
  2. Haz clic en + Webhook.
  3. Ingresa la siguiente información (todos los campos son obligatorios).
    Campo Descripción
    Nombre Nombre del webhook.
    URL URL del controlador de devolución de llamada al que se llamará cuando se active la notificación del evento. Consulta Cómo configurar el controlador de devolución de llamada.
  4. Haz clic en Guardar.

El webhook se agrega a la lista y se habilita de forma predeterminada.

Edita un webhook mediante la IU

Para editar un webhook con la IU, sigue estos pasos:

  1. Accede a la página de webhooks.
  2. Coloca el cursor sobre el webhook que deseas editar y haz clic en en el menú de acciones.
  3. Edita los campos del webhook según sea necesario.
  4. Haz clic en Actualizar webhook.

Habilita o inhabilita un webhook mediante la IU

Para habilitar o inhabilitar un webhook mediante la IU, sigue estos pasos:

  1. Accede a la página de webhooks.
  2. Coloca el cursor sobre el webhook y activa el interruptor de estado para habilitarlo o inhabilitarlo.

Borra un webhook mediante la IU

Para borrar un webhook mediante la IU, haz lo siguiente:

  1. Accede a la página de webhooks.
  2. Coloca el cursor sobre el webhook que deseas borrar y haz clic en .

El webhook se borra y se quita de la lista.

Administra webhooks mediante la API

Agrega y administra webhooks con la API como se describe en las siguientes secciones.

Visualiza todos los webhooks mediante la API

Para ver todos los webhooks, emite una solicitud GET a /mint/organizations/{org_name}/webhooks. Por ejemplo:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks" \
  -H "Content-Type: application/json " \
  -u email:password

A continuación, se muestra un ejemplo de la respuesta que se muestra:

{
  "totalRecords": 2,
  "webhooks": [
    {
      "created": 1460162656342,
      "enabled": false,
      "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
      "name": "webhook1",
      "postUrl": "http://mycompany.com/callbackhandler1",
      "updated": 1460162656342,
      "updatedBy": "joe@example.com"
    },
        {
      "created": 1460138724352,
      "createdBy": "joe@example.com",
      "enabled": true,
      "id": "a39ca777-1861-49cf-a397-c9e92ab3c09f",
      "name": "webhook2",
      "postUrl": "http://mycompany.com/callbackhandler2",
      "updated": 1460138724352,
      "updatedBy": "joe@example.com"
    }

  ]
}

Visualiza un webhook mediante la API

Envía una solicitud GET a /mint/organizations/{org_name}/webhooks/{webhook_id} para ver un solo webhook.

Por ejemplo:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" \
  -H "Content-Type: application/json " \
  -u email:password

A continuación, se proporciona un ejemplo de la respuesta.

{
   "created": 1460162656342,
   "enabled": false,
   "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
   "name": "webhook1",
   "postUrl": "http://mycompany.com/callbackhandler1",
   "updated": 1460162656342,
   "updatedBy": "joe@example.com"
 }

Agrega un webhook mediante la API

Envía una solicitud POST a /mint/organizations/{org_name}/webhooks para agregar un webhook. Debes pasar el nombre del webhook y la URL del controlador de devolución de llamada al que se llamará cuando se active la notificación del evento.

Por ejemplo, el siguiente comando crea un webhook llamado webhook3 y le asigna callbackhandler3:

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks"
  -H "Content-Type: application/json "
  -d '{
    "name": "webhook3",
    "postURL": "http://mycompany.com/callbackhandler3"
    }' \
    -u email:password

A continuación, se proporciona un ejemplo de la respuesta.

{
  "created": 1460385534555,
  "createdBy": "joe@example.com",
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler3",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Edita un webhook mediante la API

Para editar un webhook, envía una solicitud POST a /mint/organizations/{org_name}/webhooks/{webhook_id}. Pasa las actualizaciones en el cuerpo de la solicitud.

Por ejemplo, lo siguiente actualiza el controlador de devolución de llamada asociado con webhook1:

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" \
  -H "Content-Type: application/json " \
  -d '{
    "postURL": "http://mycompany.com/callbackhandler4"
  }' \
  -u email:password

A continuación, se proporciona un ejemplo de la respuesta.

{
  "created": 1460385534555,
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Habilita o inhabilita un webhook mediante la API

Para habilitar o inhabilitar un webhook, envía una solicitud POST a /mint/organizations/{org_name}/webhooks/{webhook_id}, como hiciste al momento de actualizar un webhook, y configura el atributo habilitado en el cuerpo de la solicitud como verdadero o falso, respectivamente. Si inhabilitas el webhook, no se activará cuando ocurra un evento.

Por ejemplo, lo siguiente habilita webhook3:

curl -X POST  "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" \
  -H "Content-Type: application/json " \
  -d '{
    "enabled": "true"
  }' \
  -u email:password

A continuación, se proporciona un ejemplo de la respuesta.

{
  "created": 1460385534555,
  "enabled": true,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Borra un webhook mediante la API

Envía una solicitud DELETE a /mint/organizations/{org_name}/webhooks/{webhook_id} para borrar un webhook.

Para especificar si se debe forzar o no la eliminación del webhook cuando hay procesos en curso, establece el parámetro de consulta forceDelete en true o false. El parámetro de consulta forceDelete está habilitado (true) de forma predeterminada.

Por ejemplo, lo siguiente borra webhook3:

curl -X DELETE "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" \
  -H "Content-Type: application/json " \
  -u email:password

Cómo configurar el controlador de devolución de llamada

A continuación, se muestra el formato de la solicitud JSON que se envía al controlador de devolución de llamada definido por un webhook cuando se activa la notificación de un evento. Asegúrate de que el controlador de devolución de llamada procese la solicitud de manera adecuada.

{
        "orgName": "{org_id}",
        "developerEmail": "{dev_email}",
        "developerFirstName": "{first_name}",
        "developerLastName": "{last_name}",
        "companyName": "{company_name}",
        "applicationName": "{app_name}",
        "packageName": "{api_package_name}",
        "packageId": "{api_package_id}",
        "ratePlanId": "{rateplan_id}",
        "ratePlanName": "{rateplan_name}",
        "ratePlanType": "{rateplan_type}",
        "developerRatePlanQuotaTarget": {quota_target},
        "quotaPercentUsed": {percentage_quota_used},
        "ratePlanStartDate": {rateplan_startdate}, 
        "ratePlanEndDate": {rateplan_enddate},
        "nextBillingCycleStartDate": {next_billing_cycle_startdate},
        "products": ["{api_product_name}","{api_product_name}"],
        "developerCustomAttributes": [],
        "triggerTime": {trigger_time},
        "triggerReason": "{trigger_reason}",
        "developerQuotaResetDate": "{devquota_resetdate}"
}

Configura notificaciones para un plan de tarifas ajustable

Configura notificaciones mediante webhooks para obtener un plan de tarifas ajustable mediante la IU o la API.

Configura notificaciones para un plan de tarifas ajustable con la IU

Configura notificaciones mediante webhooks para obtener un plan de tarifas ajustable mediante la IU, como se describe a continuación.

Accede al diálogo Notificaciones para ver un plan de tarifas ajustable

Accede al diálogo Notificaciones para obtener un plan de tarifas ajustable, como se describe a continuación.

Conexión de integración

Para acceder al diálogo de notificaciones con la IU de Edge, haz lo siguiente:

  1. Crea y publica un plan de frecuencia de notificaciones ajustable, como se describe en Cómo especificar los detalles del plan de notificaciones ajustable.
  2. Para acceder a la página Planes de tarifas, selecciona Publicar > Monetización > Planes de tarifas en la barra de navegación izquierda.
  3. Coloca el cursor sobre el plan del porcentaje de notificaciones ajustable publicado para mostrar las acciones.
  4. Haz clic en +Notificar.

    Se mostrará el diálogo Notificaciones.

    Nota: El plan de tarifas debe publicarse para que se muestre la acción +Notificar.

Versión clásica de Edge (nube privada)

Para acceder a la página Notificaciones:

  1. Crea un plan de frecuencia de notificaciones ajustable, como se describe en Cómo especificar los detalles del plan de notificaciones ajustable.
  2. Selecciona Publish > Packages para ver los planes de tarifas.
  3. Haz clic en + Notificar en la columna Acciones del plan de tarifas.

    Se mostrará el diálogo Notificaciones.

Agrega notificaciones para un plan de tarifas ajustable con la IU

Si quieres agregar notificaciones para un plan de tarifa ajustable en la IU, sigue estos pasos:

  1. Accede al diálogo Notificaciones.
  2. Establece la condición de notificación en Intervalos de notificación. Para ello, especifica un porcentaje de la cantidad objetivo de transacciones en las que deseas que se active una notificación. Más precisamente, presenta las siguientes características:
    • Para establecer un porcentaje exacto, ingresa el porcentaje en el campo At/From % y deja el campo To % en blanco.
    • Para establecer un rango de porcentajes, ingresa el porcentaje de inicio y finalización en los campos At/From % y To %, respectivamente, y un valor de incremento en el campo Step %. Según la configuración predeterminada, las notificaciones se envían en incrementos del 10% dentro del rango especificado.

    El campo Notify At se actualiza para reflejar cada porcentaje de la cantidad objetivo de transacciones que activarán un evento.

  3. Para establecer condiciones de notificación adicionales, haz clic en + Agregar y repite el paso 4.
  4. Configura la acción de notificación en Webhooks. Para ello, selecciona uno o más webhooks a fin de administrar el control de devolución de llamada cuando se activen las notificaciones.
  5. Haz clic en Crear notificación.

Edición de notificaciones para un plan de tarifas ajustable con la IU

Si quieres editar las notificaciones de un plan de tarifa ajustable en la IU, sigue estos pasos:

  1. Accede al diálogo Notificaciones.
  2. Haz clic en + Notificar en la columna Acciones del plan de tarifas.
  3. Haz clic en Editar.
  4. Modifica los valores según sea necesario.
  5. Haz clic en Guardar notificación.

Borra notificaciones de un plan de tarifas ajustable mediante la IU

Para borrar una condición y acción de notificación, haz lo siguiente:

  1. Accede al diálogo Notificaciones.
  2. Haz clic en + Notificar en la columna Acciones del plan de tarifas.
  3. Haz clic en Borrar notificación.

Configurar notificaciones para un plan de tarifas ajustable mediante la API

Si quieres configurar una notificación para un plan de tarifas ajustables con la API, usa el procedimiento descrito en Cómo administrar las condiciones y acciones de notificación con la API y los atributos que se describen en esta sección.

Para configurar la condición de la notificación (notificationCondition), usa los siguientes valores de atributos. Para obtener más información, consulta Propiedades de configuración para las condiciones de notificación.

Atributo Valor
RATEPLAN ID del plan de frecuencia de notificaciones ajustable.
PUBLISHED TRUE para indicar que se debe publicar el plan de frecuencia de notificaciones ajustable.
UsageTarget El porcentaje de la cantidad de transacciones objetivo en el que quieres que se active una notificación.

Este atributo te permite notificar a los desarrolladores cuando se acercan a la cantidad objetivo de transacciones (o cuando la alcanzaron) para que hayan comprado un plan de hoja de tarifas de notificación ajustable. Por ejemplo, si un desarrollador compró un plan de tasa de notificaciones ajustable y la cantidad objetivo de transacciones para el desarrollador se estableció en 1,000, puedes notificarle cuando alcanzó las 800 transacciones (80% de la cantidad objetivo de transacciones), 1,000 transacciones (100%) o 1,500 transacciones (150%).

  • Para establecer un porcentaje exacto, ingresa %= n. Por ejemplo, %= 80 enviará notificaciones cuando el porcentaje de la cantidad objetivo de transacciones alcance el 80%.
  • Para establecer un rango de porcentajes, ingresa los porcentajes de inicio y finalización, y el valor según el cual incrementarse de la siguiente manera: %= start to end by n. Por ejemplo, un valor de %= 80 to 100 by 10 enviará notificaciones cuando el porcentaje de la cantidad objetivo de transacciones alcance el 80%, el 90% y el 100%.

Para configurar la acción de notificación, en actions establece los siguientes valores. Para obtener más información, consulta Propiedades de configuración para las acciones de notificación.

Atributo Valor
actionAttribute WEBHOOK para activar un webhook.
value ID del webhook que definiste en la sección anterior, Crea webhooks con la API.

A continuación, se proporciona un ejemplo de cómo crear una condición de notificación que active un webhook cuando el porcentaje de la cantidad objetivo de transacciones alcance el 80%, el 90%, el 100%, el 110% y el 120%.

{
    "notificationCondition": [
      {
        "attribute": "RATEPLAN",
        "value": "123456"
      },
      {
        "attribute": "PUBLISHED",
        "value": "TRUE"
      },
      {
        "attribute": "UsageTarget",
        "value": "%= 80 to 120 by 10"
      }
    } 
    ],
   "actions": [{
          "actionAttribute": "WEBHOOK",
          "value": "b0d77596-142e-4606-ae2d-f55c3c6bfebe",
        }]
  }

Para obtener información sobre cómo ver, actualizar y borrar una condición y acción de notificación, consulta lo siguiente:

Códigos de respuesta de webhook

A continuación, se resumen los códigos de respuesta de webhook y cómo el sistema los interpreta.

Código de respuesta Descripción
2xx Completado correctamente
5xx

Se produjo un error en la solicitud. El sistema volverá a intentar la solicitud hasta tres veces en intervalos de 5 minutos.

Nota: Los tiempos de espera de lectura y conexión para las solicitudes de webhook son de 3 segundos cada uno, lo que puede generar solicitudes fallidas.
Other response Se produjo un error en la solicitud. El sistema no volverá a intentar la solicitud.