Metrics

Recibir métricas por webhook con la API

Con POST /metrics/get-data-async pides las métricas y la API responde al instante. El resultado llega después, en un POST a tu metrics_webhook_url. Es el camino recomendado para períodos largos, y no necesitas OAuth, revisión de app ni renovación de tokens.

La llamada

POST /api/metrics/get-data-async
Authorization: Bearer <merchant token>
x-customer-token: <customer token>

{
  "metrics_webhook_url": "https://sua-aplicacao.com/webhooks/metricas",
  "customer_integration": "<connection uuid>",
  "start": "2026-08-01",
  "end": "2026-08-31",
  "metrics": [
    {
      "id": "f35a44ce-dac5-4188-aace-5c44a8952176",
      "reference_key": "ig:story_replies",
      "component": "number_v1",
      "metrics": [
        "replies"
      ]
    }
  ]
}

Qué puedes hacer

  • Pedir varias métricas de una conexión en una sola llamada, cada una con su component.
  • Recibir el resultado en un endpoint tuyo, sin mantener la solicitud abierta mientras se recolectan los datos.
  • Usar los mismos reference_keys del catálogo GET /metrics/{integration_slug} que la versión síncrona.
  • Pedir también un período de comparación con comparison_start y comparison_end.

Reglas y límites

  • La respuesta inmediata es 200 con success: true y el mensaje Metrics will be sent to your webhook.
  • El cuerpo entregado al webhook es el mapa de métricas en la raíz, sin el envoltorio data de la versión síncrona. Cada clave es el id (UUID) que enviaste.
  • metrics_webhook_url debe ser http o https y apuntar a una dirección pública: IP privadas, loopback y link-local devuelven 422.
  • Cada llamada lee una sola conexión (customer_integration) y exige el x-customer-token del cliente dueño de ella.
  • En el período de prueba, start puede retroceder como máximo 62 días y metrics acepta hasta 15 ítems (trial_history_limit y trial_metrics_limit).

Campos principales

CampoTipoObligatorioDescripción
metrics_webhook_urlstringSíURL http o https pública que recibe las métricas. Se rechazan IP privadas, loopback y link-local.
customer_integrationstringSíUUID de la conexión del cliente de donde se leen las métricas. Una por llamada.
startstringSíInicio del período (YYYY-MM-DD). Debe ser menor o igual a end.
endstringSíFin del período (YYYY-MM-DD).
metricsarraySíLista de métricas pedidas, al menos una. Cada ítem trae id, reference_key, component y metrics.
metrics.reference_keystringSíIdentificador de la métrica, del catálogo GET /metrics/{integration_slug}.

Para quién

  • Informes mensuales en lote

    Tu SaaS lanza la recolección de todos los clientes por la noche y procesa cada resultado cuando llega al webhook, sin hilos bloqueados esperando.

  • Dashboards de agencia

    Pide el año completo de una cuenta al cargar el panel y actualiza la pantalla cuando el webhook entregue los datos.

  • Agentes de IA

    Un agente pide la recolección, sigue con otras tareas y retoma el análisis cuando el webhook trae las métricas.

Preguntas frecuentes

¿Cuál es la diferencia entre get-data y get-data-async?

get-data mantiene la solicitud abierta y responde con los datos dentro de un objeto data. get-data-async responde al instante y entrega las métricas en un POST a tu metrics_webhook_url, sin el envoltorio data. Para períodos largos, usa la asíncrona.

¿Puedo apuntar el webhook a localhost?

No. La URL se valida y debe ser pública: IP privadas, loopback y link-local se rechazan con 422. Para probar en local, usa un túnel con URL pública.

¿Puedo recolectar de varias cuentas en una sola llamada?

No. Cada llamada lee una conexión, indicada en customer_integration. Para varias cuentas, haz una llamada por conexión.

Relacionadas

Ver todo lo que puedes hacer con Metrics

Mira Connect aplicado a tu producto.

Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.