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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| metrics_webhook_url | string | Sim | URL http ou https pública que recebe as métricas. IPs privados, loopback e link-local são recusados. |
| customer_integration | string | Sim | UUID da conexão do cliente de onde as métricas são lidas. Uma por chamada. |
| start | string | Sim | Início do período (YYYY-MM-DD). Deve ser menor ou igual a end. |
| end | string | Sim | Fim do período (YYYY-MM-DD). |
| metrics | array | Sim | Lista de métricas pedidas, ao menos uma. Cada item traz id, reference_key, component e metrics. |
| metrics.reference_key | string | Sim | Identificador 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.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
