Metrics

Receber métricas por webhook pela API

Com POST /metrics/get-data-async você pede as métricas e a API responde na hora. O resultado chega depois, num POST para a sua metrics_webhook_url. É o caminho recomendado para períodos longos, e você não precisa de OAuth, revisão de app nem renovação de token.

A chamada

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"
      ]
    }
  ]
}

O que dá para fazer

  • Pedir várias métricas de uma conexão numa única chamada, cada uma com o seu component.
  • Receber o resultado em um endpoint seu, sem manter a requisição aberta enquanto os dados são coletados.
  • Usar os mesmos reference_keys do catálogo GET /metrics/{integration_slug} que a versão síncrona.
  • Pedir também um período de comparação com comparison_start e comparison_end.

Regras e limites

  • A resposta imediata é 200 com success: true e a mensagem Metrics will be sent to your webhook.
  • O corpo entregue no webhook é o mapa de métricas na raiz, sem o envelope data da versão síncrona. Cada chave é o id (UUID) que você enviou.
  • metrics_webhook_url precisa ser http ou https e apontar para um endereço público: IP privado, loopback e link-local retornam 422.
  • Cada chamada lê uma única conexão (customer_integration) e exige o x-customer-token do cliente dono dela.
  • No período de teste, start pode voltar no máximo 62 dias e metrics aceita até 15 itens (trial_history_limit e trial_metrics_limit).

Campos principais

CampoTipoObrigatórioDescrição
metrics_webhook_urlstringSimURL http ou https pública que recebe as métricas. IPs privados, loopback e link-local são recusados.
customer_integrationstringSimUUID da conexão do cliente de onde as métricas são lidas. Uma por chamada.
startstringSimInício do período (YYYY-MM-DD). Deve ser menor ou igual a end.
endstringSimFim do período (YYYY-MM-DD).
metricsarraySimLista de métricas pedidas, ao menos uma. Cada item traz id, reference_key, component e metrics.
metrics.reference_keystringSimIdentificador da métrica, do catálogo GET /metrics/{integration_slug}.

Para quem

  • Relatórios mensais em lote

    Seu SaaS dispara a coleta de todos os clientes à noite e processa cada resultado quando ele chega no webhook, sem threads presas esperando.

  • Dashboards de agência

    Peça o ano inteiro de uma conta no carregamento do painel e atualize a tela quando o webhook entregar os dados.

  • Agentes de IA

    Um agente pede a coleta, segue com outras tarefas e retoma a análise quando o webhook traz as métricas.

Perguntas frequentes

Qual a diferença entre get-data e get-data-async?

get-data mantém a requisição aberta e responde com os dados num objeto data. get-data-async responde na hora e entrega as métricas num POST para a sua metrics_webhook_url, sem o envelope data. Para períodos longos, use a assíncrona.

Posso apontar o webhook para localhost?

Não. A URL é validada e precisa ser pública: IP privado, loopback e link-local são recusados com 422. Para testar localmente, use um túnel com URL pública.

Posso coletar de várias contas numa chamada só?

Não. Cada chamada lê uma conexão, informada em customer_integration. Para várias contas, faça uma chamada por conexão.

Relacionadas

Ver tudo que dá para fazer em Metrics

Veja o Connect aplicado ao seu produto.

Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.