> ## Documentation Index
> Fetch the complete documentation index at: https://help.withallo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Recevez des notifications en temps réel lorsque des événements d'appels, SMS et contacts se produisent dans votre compte Allo

Les webhooks envoient des notifications HTTP automatiques à votre serveur lorsque des événements se produisent dans votre compte Allo — un appel se termine, un SMS arrive, un contact est créé, et plus encore.

## Ce que vous pouvez faire avec les webhooks

* Enregistrer les appels et messages dans votre CRM ou base de données
* Déclencher des workflows lorsque les appels se terminent ou que des SMS arrivent
* Synchroniser les contacts avec des systèmes externes
* Construire des tableaux de bord et alertes en temps réel

## Événements disponibles

| Événement         | Description                                                |
| ----------------- | ---------------------------------------------------------- |
| `call.received`   | Appel entrant commence à sonner                            |
| `call.triggered`  | Appel sortant initié                                       |
| `call.answered`   | Appel décroché de l'autre côté                             |
| `call.completed`  | Appel terminé avec enregistrement, transcription et résumé |
| `tag.added`       | Tag ajouté à un appel                                      |
| `tag.removed`     | Tag supprimé d'un appel                                    |
| `sms.received`    | SMS entrant reçu                                           |
| `sms.sent`        | SMS sortant envoyé                                         |
| `contact.created` | Contact créé                                               |
| `contact.updated` | Contact mis à jour                                         |

## Comment configurer les webhooks

<Tabs>
  <Tab title="Via l'API">
    <Steps>
      <Step title="Obtenir une clé API">
        Allez dans [Paramètres > API](https://web.withallo.com/settings/api) et créez une clé API avec le scope `WEBHOOKS_READ_WRITE`.
      </Step>

      <Step title="Créer un endpoint webhook">
        ```bash theme={null}
        curl -X POST https://api.withallo.com/v2/webhooks \
          -H "Authorization: YOUR_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{
            "url": "https://example.com/webhooks/allo",
            "topics": ["call.completed", "sms.received"]
          }'
        ```
      </Step>

      <Step title="Traiter les requêtes entrantes">
        Votre serveur reçoit une requête POST pour chaque événement. Retournez un code de statut `200` dans les 20 secondes pour confirmer la réception.
      </Step>

      <Step title="Vérifier les signatures">
        Chaque webhook inclut une signature cryptographique. Vérifiez-la pour vous assurer que la requête provient d'Allo. Voir [Vérification des signatures](/fr/v2/api-reference/webhooks/verifying-signatures).
      </Step>
    </Steps>
  </Tab>

  <Tab title="Via l'application mobile">
    <Steps>
      <Step title="Ouvrir les intégrations">
        Allez dans **Paramètres > Intégrations > Webhooks** dans l'application mobile Allo.
      </Step>

      <Step title="Activer les webhooks">
        Activez le switch webhook.
      </Step>

      <Step title="Configurer votre URL">
        Entrez l'URL HTTPS de votre endpoint. L'URL doit être accessible publiquement.
      </Step>

      <Step title="Sélectionner les événements">
        Choisissez les événements que vous souhaitez recevoir.
      </Step>

      <Step title="Tester la connexion">
        Appuyez sur **Tester** pour envoyer un événement de test à votre endpoint et vérifier qu'il fonctionne.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Format du payload webhook

Chaque webhook utilise la même enveloppe :

```json theme={null}
{
  "topic": "call.completed",
  "version": "2.0",
  "timestamp": "2025-03-15T14:45:00.000Z",
  "data": {
    "id": "cll_2NfDKEm9sF8xK3pQr1Zt",
    "from_number": "+33612345678",
    "to": "+33112345678",
    "type": "INBOUND",
    "result": "ANSWERED",
    "summary": "Le client a appelé pour une question de facturation.",
    "recording_url": "https://storage.withallo.com/recordings/abc123.mp3"
  }
}
```

Pour la spécification complète des payloads de chaque événement, voir le [Catalogue des événements](/fr/v2/api-reference/webhooks/event-catalog).

## Sécurité

* L'URL de votre endpoint doit utiliser **HTTPS**.
* Chaque webhook inclut une signature cryptographique dans l'en-tête `webhook-signature`. [Vérifiez-la](/fr/v2/api-reference/webhooks/verifying-signatures) pour vous assurer que la requête est authentique.
* Conservez votre secret de signature de manière sécurisée — traitez-le comme un mot de passe.

## Fiabilité

* Allo réessaie les livraisons échouées jusqu'à **8 fois** sur environ 27,5 heures avec un backoff exponentiel.
* Si votre endpoint échoue de façon continue pendant 5 jours, il est automatiquement désactivé.
* Vous pouvez [récupérer les événements manqués](/fr/v2/api-reference/webhooks/delivery-and-retries#bulk-recovery) en les rejouant après avoir corrigé votre endpoint.

Voir [Livraison et nouvelles tentatives](/fr/v2/api-reference/webhooks/delivery-and-retries) pour le calendrier complet des réessais.

## Exemples d'implémentation

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const express = require("express");
    const app = express();

    app.post(
      "/webhooks/allo",
      express.raw({ type: "application/json" }),
      (req, res) => {
        const event = JSON.parse(req.body);

        switch (event.topic) {
          case "call.completed":
            console.log("Appel terminé :", event.data.id);
            break;
          case "sms.received":
            console.log("SMS de :", event.data.from_number);
            break;
        }

        res.sendStatus(200);
      }
    );

    app.listen(3000);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from flask import Flask, request

    app = Flask(__name__)

    @app.route("/webhooks/allo", methods=["POST"])
    def handle_webhook():
        event = request.get_json()

        if event["topic"] == "call.completed":
            print(f"Appel terminé : {event['data']['id']}")
        elif event["topic"] == "sms.received":
            print(f"SMS de : {event['data']['from_number']}")

        return "", 200
    ```
  </Tab>
</Tabs>

## Dépannage

<AccordionGroup>
  <Accordion title="Le webhook ne reçoit pas d'événements">
    Vérifiez que votre endpoint est accessible publiquement via HTTPS. Vérifiez que le webhook est activé et abonné aux bons types d'événements. Utilisez l'[endpoint de test](/fr/v2/api-reference/webhooks/testing) pour vérifier.
  </Accordion>

  <Accordion title="Erreurs de timeout">
    Votre endpoint doit répondre dans les 20 secondes. Retournez `200` immédiatement et traitez l'événement en arrière-plan.
  </Accordion>

  <Accordion title="Réception d'événements en double">
    C'est attendu — Allo garantit une livraison « au moins une fois ». Utilisez l'en-tête `webhook-id` pour dédupliquer. Voir [Bonnes pratiques](/fr/v2/api-reference/webhooks/best-practices).
  </Accordion>

  <Accordion title="La vérification de signature échoue">
    Assurez-vous d'utiliser le corps brut de la requête (pas le JSON parsé) pour la vérification. Vérifiez que votre secret de signature est correct et que l'horloge de votre serveur est précise. Voir [Vérification des signatures](/fr/v2/api-reference/webhooks/verifying-signatures).
  </Accordion>
</AccordionGroup>

## Besoin d'aide ?

<CardGroup cols={2}>
  <Card title="Référence API complète" icon="book" href="/fr/v2/api-reference/webhooks/overview">
    Documentation complète des webhooks API
  </Card>

  <Card title="Contacter le support" icon="headset" href="mailto:support@withallo.com">
    Obtenir de l'aide de l'équipe Allo
  </Card>
</CardGroup>