en
Webhook Integration Guide

Alvio Webhook Integration Guide

This document explains how to send lead/contact data to Alvio via HTTPS POST. You can use the Test environment first, then switch to Production once validated.

1. Environments and authentication

Alvio exposes two webhook endpoints:

EnvironmentEndpointAuthentication
Testhttps://webhooks.alvio.ai/6i8qsza7zhyt76Header api-key: test
ProductionContact usHeader api-key: contact us

All requests must:

  • Use the POST method
  • Include the Content-Type: application/json header
  • Include the api-key: <your key> header

2. Payload schema

Alvio accepts a flexible JSON payload. The fields below are recommended, but you can include any additional fields your systems produce—Alvio will accept and preserve them for routing/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": "en",
    "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"
  },
  "assignees": [
    {
      "role": "sales",
      "nom": "Dupont",
      "prenom": "Jean",
      "email": "jean.dupont@example.com",
      "slack_id": "U1234567890"
    },
    {
      "role": "sdr",
      "nom": "Martin",
      "prenom": "Sophie",
      "email": "sophie.martin@example.com",
      "slack_id": "U0987654321"
    }
  ]
}

Field notes

  • phone_number — Required. Primary contact identifier. Prefer E.164 format (e.g. +336...). If not available, send as-is; Alvio will attempt normalization.
  • crm_contact_id — Optional. Your internal ID for tracing and reference.
  • crm_deal_id — Optional. Your opportunity/deal ID for tracing.
  • lifecycle_stage — Optional. Contact status: lead (default), customer, or churned. If omitted, contact is treated as lead. See the lifecycle tracking guide for details.
  • contact — Basic identity fields (extend as needed: company, role, siret, etc.).
  • campaign — Acquisition metadata (extend as needed: utm_source, utm_medium, adset_id, etc.).
  • custom — Free-form object for any extra attributes. Optional; you can also put extra keys at root.
  • sales — Assigned sales rep info (optional): nom, prenom, email, lien_calendrier, slack_id, phone_number.
  • sdr — Assigned SDR info (optional): same fields as sales.

Assigning one or more people to a conversation

To assign multiple people to the same conversation (e.g. co-piloting, dedicated team), you can use an assignees array in addition to or instead of sales / sdr:

  • assignees — Optional array. Each item has the same fields as sales/sdr plus role (e.g. sales, sdr, support).
  • You can combine assignees with sales and sdr: in that case, the main sales rep and SDR are set via sales and sdr, and others via assignees.

Flexibility: You can add as many fields as you want in contact, campaign, custom, or at root. Alvio will store them and make them available in your workspace.

3. Minimal vs full examples

Minimal payload

{
  "phone_number": "+33612345678"
}

Full payload

{
  "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": "Alpine Farm"
  },
  "campaign": {
    "source": "facebook",
    "ad_id": "9876543210",
    "campaign_name": "facebook_video_august",
    "utm_source": "fb",
    "utm_medium": "cpc"
  },
  "custom": {
    "preferred_language": "en",
    "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. cURL examples

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. Expected responses

  • 200 OK — Payload accepted.
{"status":"SUCCESS","message":"Request successfully handled. Request ID: "req_5bT84S86WHssLLHWD2FX","request_id":"req_5bT84S86WHssLLHWD2FX"}
  • 4xx — Client error (e.g. invalid JSON, missing/invalid api-key, wrong Content-Type).
  • 5xx — Server error (rare). Retry with backoff.

6. Best practices

  • Content-Type: Always application/json with valid JSON (double quotes, commas, no trailing commas).
  • Retries: On transient failures (HTTP 5xx/429 or timeouts), retry with exponential backoff.
  • Timeouts: Use a client timeout of 10 seconds or more.
  • Size limits: Keep payloads < 2 MB.
  • Security: Treat your api-key as a secret; rotate it if compromised.

Need help with integration? Contact our technical team for personalized support.

WhatsApp Business API GuideCustomer Lifecycle Tracking