Saltar al contenido
AurionAI

API para desarrolladores: uso y webhooks

4 min de lecturaPor Emmanuel Yazbeck

Las páginas de la API para desarrolladores muestran cómo los programas utilizan la API de AurionAI y permiten enviar eventos de AurionAI a sus propios sistemas mediante webhooks.

Disponibilidad: todos los perfiles. Solo administradores.

Requisitos previos

  • Tiene el rol Propietario o Administrador. Otros roles no pueden abrir estas páginas.
  • Para webhooks: una dirección HTTPS en su sistema que acepte solicitudes POST con un cuerpo JSON.

Abrir las páginas de la API para desarrolladores

  1. En la barra superior, seleccione su nombre o imagen para abrir el menú de usuario.
  2. Seleccione Configuración de inquilinos.
  3. Vaya a la tarjeta API para desarrolladores.
  4. Seleccione Panel de uso de la API o Gestión de webhooks.

La tarjeta Developer API en la página de configuración del tenant.

Revisar el uso de la API

La página «API Usage Dashboard» muestra el tráfico de la API de AurionAI para su organización.

  1. En «Window», elija «Last 1 day», «Last 7 days» o «Last 30 days». El valor predeterminado es siete días.
  2. Consulte los cuatro totales: «Total Requests», «Error Rate», «Rate-Limit Hits» y «Webhook Success».
  3. Consulte «Top API Paths» para ver qué direcciones se llaman con más frecuencia, junto con sus errores.
  4. Consulte «Daily Trend» para ver el tráfico por día.
  5. Seleccione «Refresh» para cargar los datos más recientes.

Registrar un webhook

  1. En la página «Webhook Management», vaya a «Create Subscription».
  2. En «Target URL», escriba la dirección HTTPS de su receptor.
  3. En «Events», seleccione los eventos que desea recibir. Los eventos están agrupados: conversaciones, mensajes, contactos, tickets, llamadas, base de conocimiento y sistema.
  4. Seleccione «Create webhook».
  5. Aparece un cuadro de diálogo con el secreto de firma. Seleccione «Copy secret» y guarde el secreto en un lugar seguro. AurionAI lo muestra únicamente esta vez.
  6. Seleccione «I have saved my secret».

El nuevo webhook aparece en «Subscriptions» con el estado «Active».

Verificar la firma de un webhook

Cada entrega es una solicitud POST con un cuerpo JSON y las siguientes cabeceras:

  • X-Webhook-Event: el nombre del evento, por ejemplo ticket.created.
  • X-Webhook-Timestamp: la hora de la entrega.
  • X-Webhook-Signature: la firma de la entrega.

Para comprobar que una entrega proviene de AurionAI:

  1. Tome el valor de X-Webhook-Timestamp, un punto y el cuerpo sin procesar de la solicitud, en este orden.
  2. Calcule un HMAC-SHA256 de este texto con su secreto de firma.
  3. Escriba el resultado en hexadecimal y compárelo con X-Webhook-Signature. Acepte la entrega solo cuando sean iguales.

Probar, pausar o eliminar un webhook

  • Seleccione «Send test» para enviar una entrega de prueba. Un webhook pausado no puede recibir una prueba.
  • Seleccione «Pause» para detener las entregas durante un tiempo y «Resume» para reanudarlas.
  • Seleccione «Delete» y confirme para eliminar el webhook.
  • La página muestra las entregas más recientes, con su estado, el número de intentos y el estado HTTP de su receptor.

Resultado

AurionAI envía cada evento seleccionado a su dirección. Una entrega se considera correcta cuando su receptor responde con un estado 2xx. En caso contrario, AurionAI lo intenta de nuevo más tarde, hasta un máximo de cinco intentos en total.

Si algo va mal

  • «Webhook URL is required.» Escriba la dirección de su receptor.
  • «Select at least one event to subscribe to.» Seleccione al menos un evento.
  • Un mensaje indica que la URL del webhook debe comenzar por https. AurionAI envía webhooks únicamente a direcciones HTTPS.
  • Un mensaje indica que la dirección está bloqueada o no se puede resolver. AurionAI rechaza las direcciones privadas, locales y desconocidas. Utilice una dirección pública que se resuelva en DNS.
  • La firma no coincide. Utilice el cuerpo sin procesar tal como se recibió, antes de cualquier análisis. Utilice el secreto de este webhook. Si ha perdido el secreto, elimine el webhook y vuelva a crearlo.
  • Las entregas fallan. Compruebe el estado HTTP en la lista de entregas. Su receptor debe responder con un estado 2xx.
  • «No webhooks configured» en «Webhook Success». Su organización aún no tiene ningún webhook de desarrollador.

Artículos relacionados

¿Sigue con dudas? Envíe una solicitud o .