Metrics

Recevoir des métriques par webhook via l'API

Avec POST /metrics/get-data-async, vous demandez les métriques et l'API répond immédiatement. Le résultat arrive ensuite dans un POST vers votre metrics_webhook_url. C'est la voie recommandée pour les longues périodes, sans OAuth, sans revue d'app ni renouvellement de token.

L'appel

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

Ce que vous pouvez faire

  • Demander plusieurs métriques d'une connexion en un seul appel, chacune avec son component.
  • Recevoir le résultat sur un endpoint à vous, sans garder la requête ouverte pendant la collecte.
  • Utiliser les mêmes reference_keys du catalogue GET /metrics/{integration_slug} que la version synchrone.
  • Demander aussi une période de comparaison avec comparison_start et comparison_end.

Règles et limites

  • La réponse immédiate est 200 avec success: true et le message Metrics will be sent to your webhook.
  • Le corps livré au webhook est la table des métriques à la racine, sans l'enveloppe data de la version synchrone. Chaque clé est l'id (UUID) que vous avez envoyé.
  • metrics_webhook_url doit être http ou https et pointer vers une adresse publique : IP privées, loopback et link-local renvoient 422.
  • Chaque appel lit une seule connexion (customer_integration) et exige le x-customer-token du client qui en est propriétaire.
  • En période d'essai, start peut remonter de 62 jours au maximum et metrics accepte jusqu'à 15 éléments (trial_history_limit et trial_metrics_limit).

Champs principaux

ChampTypeObligatoireDescription
metrics_webhook_urlstringOuiURL http ou https publique qui reçoit les métriques. Les IP privées, loopback et link-local sont refusées.
customer_integrationstringOuiUUID de la connexion du client dont les métriques sont lues. Une par appel.
startstringOuiDébut de la période (YYYY-MM-DD). Doit être inférieur ou égal à end.
endstringOuiFin de la période (YYYY-MM-DD).
metricsarrayOuiListe des métriques demandées, au moins une. Chaque élément porte id, reference_key, component et metrics.
metrics.reference_keystringOuiIdentifiant de la métrique, issu du catalogue GET /metrics/{integration_slug}.

Pour qui

  • Rapports mensuels en lot

    Votre SaaS lance la collecte de tous les clients la nuit et traite chaque résultat à son arrivée sur le webhook, sans threads bloqués.

  • Tableaux de bord d'agence

    Demandez toute l'année d'un compte au chargement du panneau et mettez l'écran à jour quand le webhook livre les données.

  • Agents IA

    Un agent demande la collecte, passe à d'autres tâches et reprend l'analyse quand le webhook apporte les métriques.

Questions fréquentes

Quelle différence entre get-data et get-data-async ?

get-data garde la requête ouverte et répond avec les données dans un objet data. get-data-async répond immédiatement et livre les métriques dans un POST vers votre metrics_webhook_url, sans l'enveloppe data. Pour les longues périodes, utilisez l'asynchrone.

Puis-je pointer le webhook vers localhost ?

Non. L'URL est validée et doit être publique : IP privées, loopback et link-local sont refusées avec 422. Pour tester en local, utilisez un tunnel avec une URL publique.

Puis-je collecter plusieurs comptes en un seul appel ?

Non. Chaque appel lit une connexion, indiquée dans customer_integration. Pour plusieurs comptes, faites un appel par connexion.

Voir aussi

Voir tout ce que vous pouvez faire avec Metrics

Voyez Connect appliqué à votre produit.

Essayez-le pendant 15 jours sans carte, ou présentez votre cas à notre équipe.