Guide d'intégration Webhook

Guide d'intégration Webhook Alvio

Ce document explique comment envoyer des données de leads/contacts à Alvio via HTTPS POST. Vous pouvez utiliser l'environnement Test d'abord, puis passer en Production une fois validé.

1. Environnements et authentification

Alvio expose deux endpoints webhook :

EnvironnementEndpointAuthentification
Testhttps://webhooks.alvio.ai/6i8qsza7zhyt76Header api-key: test
ProductionNous contacterHeader api-key: nous contacter

Toutes les requêtes doivent :

  • Utiliser la méthode POST
  • Inclure le header Content-Type: application/json
  • Inclure le header api-key: <votre clé>

2. Schéma du payload

Alvio accepte un payload JSON flexible. Les champs ci-dessous sont recommandés, mais vous pouvez inclure tous les champs supplémentaires que vos systèmes produisent — Alvio les acceptera et les préservera pour le routage/analytics.

{
  "phone_number": "+33612345678",
  "crm_contact_id": "12345-abc",
  "crm_deal_id": "deal-12345-abc",
  "lifecycle_stage": "lead",
  "contact": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "postal_code": "75001"
  },
  "campaign": {
    "source": "facebook",
    "ad_id": "9876543210",
    "campaign_name": "facebook_video_august"
  },
  "custom": {
    "preferred_language": "fr",
    "notes": "Called in, wants delivery next week",
    "anything_else": "Any extra keys are allowed here or at root"
  },
  "sales": {
    "nom": "Dupont",
    "prenom": "Jean",
    "email": "jean.dupont@example.com",
    "lien_calendrier": "https://calendly.com/jean-dupont",
    "slack_id": "U1234567890",
    "phone_number": "+33698765432"
  },
  "sdr": {
    "nom": "Martin",
    "prenom": "Sophie",
    "email": "sophie.martin@example.com",
    "lien_calendrier": "https://calendly.com/sophie-martin",
    "slack_id": "U0987654321",
    "phone_number": "+33612345678"
  }
}

Notes sur les champs

  • phone_number — Requis. Identifiant principal du contact. Préférez le format E.164 (ex: +336...). Si non disponible, envoyez brut ; Alvio tentera une normalisation.
  • crm_contact_id — Optionnel. Votre identifiant interne pour aider à tracer et référencer.
  • crm_deal_id — Optionnel. Votre identifiant d'opportunité/deal pour aider à tracer.
  • lifecycle_stage — Optionnel. Statut du contact : lead (par défaut), customer, ou churned. Si non spécifié, le contact sera considéré comme lead. Voir le guide de suivi du cycle de vie pour plus de détails.
  • contact — Champs d'identité de base (étendez selon besoin : company, role, siret, etc.).
  • campaign — Métadonnées d'acquisition (étendez selon besoin : utm_source, utm_medium, adset_id, etc.).
  • custom — Objet libre pour tous attributs supplémentaires. Optionnel ; alternativement, placez des clés supplémentaires à la racine.
  • sales — Informations du commercial assigné (optionnel) : nom, prenom, email, lien_calendrier, slack_id, phone_number.
  • sdr — Informations du SDR assigné (optionnel) : nom, prenom, email, lien_calendrier, slack_id, phone_number.

Flexibilité : Vous pouvez ajouter autant de champs que vous voulez soit dans contact, campaign, custom, ou au niveau racine. Alvio les stockera et les rendra disponibles dans votre workspace.

3. Exemples minimal vs complet

Payload minimal

{
  "phone_number": "+33612345678"
}

Payload complet

{
  "phone_number": "+33612345678",
  "crm_contact_id": "12345-abc",
  "crm_deal_id": "deal-12345-abc",
  "lifecycle_stage": "customer",
  "contact": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "postal_code": "75001",
    "company": "Ferme des Alpes"
  },
  "campaign": {
    "source": "facebook",
    "ad_id": "9876543210",
    "campaign_name": "facebook_video_august",
    "utm_source": "fb",
    "utm_medium": "cpc"
  },
  "custom": {
    "preferred_language": "fr",
    "budget_range": "5-10k",
    "accepts_whatsapp": true
  },
  "conversion": {
    "date": "2025-01-15",
    "amount": 5000,
    "currency": "EUR"
  },
  "sales": {
    "nom": "Dupont",
    "prenom": "Jean",
    "email": "jean.dupont@example.com",
    "lien_calendrier": "https://calendly.com/jean-dupont",
    "slack_id": "U1234567890",
    "phone_number": "+33698765432"
  },
  "sdr": {
    "nom": "Martin",
    "prenom": "Sophie",
    "email": "sophie.martin@example.com",
    "lien_calendrier": "https://calendly.com/sophie-martin",
    "slack_id": "U0987654321",
    "phone_number": "+33612345678"
  }
}

4. Exemples cURL

Test

curl -X POST 'https://webhooks.alvio.ai/6i8qsza7zhyt76' \
  -H 'api-key: test' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "+33612345678",
    "crm_contact_id": "12345-abc",
    "crm_deal_id": "deal-12345-abc", 
    "contact": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "postal_code": "75001"
    },
    "campaign": {
      "source": "facebook",
      "ad_id": "9876543210",
      "campaign_name": "facebook_video_august"
    },
    "sales": {
      "nom": "Dupont",
      "prenom": "Jean",
      "email": "jean.dupont@example.com",
      "lien_calendrier": "https://calendly.com/jean-dupont",
      "slack_id": "U1234567890",
      "phone_number": "+33698765432"
    },
    "sdr": {
      "nom": "Martin",
      "prenom": "Sophie",
      "email": "sophie.martin@example.com",
      "lien_calendrier": "https://calendly.com/sophie-martin",
      "slack_id": "U0987654321",
      "phone_number": "+33612345678"
    }
  }'

Production

curl -X POST 'https://webhooks.alvio.ai/celqs5mur1l7p8' \
  -H 'api-key: 48FBBD88-78C1-4AC8-AFCB-1475C5F7236D' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "+33612345678",
    "crm_contact_id": "12345-abc",
    "crm_deal_id": "deal-12345-abc", 
    "contact": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "postal_code": "75001"
    },
    "campaign": {
      "source": "facebook",
      "ad_id": "9876543210",
      "campaign_name": "facebook_video_august"
    },
    "custom": {
      "notes": "VIP lead"
    },
    "sales": {
      "nom": "Dupont",
      "prenom": "Jean",
      "email": "jean.dupont@example.com",
      "lien_calendrier": "https://calendly.com/jean-dupont",
      "slack_id": "U1234567890",
      "phone_number": "+33698765432"
    },
    "sdr": {
      "nom": "Martin",
      "prenom": "Sophie",
      "email": "sophie.martin@example.com",
      "lien_calendrier": "https://calendly.com/sophie-martin",
      "slack_id": "U0987654321",
      "phone_number": "+33612345678"
    }
  }'

5. Réponses attendues

  • 200 OK — Payload accepté.
{"status":"SUCCESS","message":"Request successfully handled. Request ID: "req_5bT84S86WHssLLHWD2FX","request_id":"req_5bT84S86WHssLLHWD2FX"}
  • 4xx — Erreur client (ex: JSON invalide, api-key manquant/invalide, mauvais Content-Type).
  • 5xx — Erreur serveur (rare). Réessayez avec backoff.

6. Bonnes pratiques

  • Content-Type : Toujours application/json avec JSON valide (guillemets doubles, virgules, pas de virgules finales).
  • Nouvelles tentatives : Sur les échecs transitoires (HTTP 5xx/429 ou timeouts), réessayez avec backoff exponentiel.
  • Timeouts : Utilisez un timeout client de 10 secondes ou plus.
  • Limites de taille : Gardez les payloads < 2 MB.
  • Sécurité : Traitez votre api-key comme un secret ; faites-la tourner si compromise.

Besoin d'aide pour l'intégration ? Contactez notre équipe technique pour un accompagnement personnalisé.

Guide WhatsApp Business APISuivi du cycle de vie client