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

# Configurer un webhook

> Recevez les changements de statut de vos commandes en temps réel

Ce guide explique comment enregistrer un webhook pour être notifié automatiquement des événements Paps, plutôt que d'interroger l'API en continu.

## Enregistrer un webhook

**`POST /webhook`**

### Authentification

```http theme={null}
x-api-key: {{PAPS_API_KEY}}
```

### Body

```json theme={null}
{
  "clientId": "{{CLIENT_ID}}",
  "name": "Notifications statut commande",
  "url": "https://votre-domaine.com/webhooks/paps",
  "event": "STATUS_UPDATED",
  "headers": {
    "Authorization": "Bearer votre-secret-partage"
  }
}
```

### Champs

| Champ      | Type   | Requis | Description                                                                                                                                                                              |
| ---------- | ------ | -----: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientId` | string |    oui | Identifiant du client                                                                                                                                                                    |
| `name`     | string |    oui | Nom du webhook                                                                                                                                                                           |
| `url`      | string |    oui | URL qui recevra les événements                                                                                                                                                           |
| `event`    | string |    oui | Type d'événement. Seule valeur disponible : `STATUS_UPDATED`.                                                                                                                            |
| `headers`  | object |    non | En-têtes additionnels envoyés avec chaque requête webhook. Vous pouvez y définir n'importe quel champ, pas uniquement `Authorization` : ils sont retransmis tels quels sur chaque appel. |

### Réponse — `201`

Le webhook est créé.

## L'événement `StatusUpdated`

Un changement de statut de colis déclenche un appel `POST` vers l'URL configurée, avec les en-têtes définis dans `headers`.

```json theme={null}
{
  "status": "OnDelivery",
  "message": "The driver confirmed that he received all the parcels from the runsheet that contains the parcels and starts the parcels delivery",
  "data": {
    "uid": "...",
    "parcelId": "...",
    "orderId": "...",
    "packageSize": "XL",
    "description": "iPhone 13 Pro Max",
    "price": 10000,
    "refClient": "4759XHG0MKH",
    "amountCollect": 10000,
    "reason": null,
    "reasonText": null,
    "updatedAt": "2026-08-01T10:05:00.000Z"
  }
}
```

<Note>
  Le champ `message` est actuellement rédigé en anglais. Voir [Statuts de livraison](/concepts/delivery-statuses) pour la liste complète des valeurs de `status` et leur signification.
</Note>

| Champ                | Type   | Description                               |
| -------------------- | ------ | ----------------------------------------- |
| `status`             | string | Nouveau statut du colis                   |
| `message`            | string | Message lisible décrivant le statut       |
| `data`               | object | Détails du colis concerné                 |
| `data.uid`           | string | Identifiant unique du colis               |
| `data.parcelId`      | string | Identifiant interne du colis              |
| `data.orderId`       | string | Identifiant de la commande associée       |
| `data.packageSize`   | string | Format du colis                           |
| `data.description`   | string | Description du colis                      |
| `data.price`         | number | Valeur du colis, en FCFA                  |
| `data.refClient`     | string | Référence fournie par le client           |
| `data.amountCollect` | number | Montant à collecter, en FCFA              |
| `data.reason`        | string | Raison associée au statut (si applicable) |
| `data.reasonText`    | string | Description de la raison (si applicable)  |
| `data.updatedAt`     | string | Date de mise à jour du statut             |

<Info>
  `STATUS_UPDATED` est le seul événement disponible actuellement. D'autres événements pourront être ajoutés par la suite.
</Info>

## Sécuriser l'URL de votre webhook

* Exposez votre endpoint uniquement en HTTPS.
* Utilisez le champ `headers` pour transmettre un secret partagé (par exemple un token dans l'en-tête `Authorization`) et vérifiez-le à la réception de chaque appel. C'est le mécanisme à utiliser pour authentifier les appels entrants.

## Répondre rapidement avec un statut `2xx`

Votre endpoint doit répondre le plus vite possible avec un code `2xx` pour accuser réception de l'événement. Traitez le contenu de manière asynchrone (file d'attente, job en arrière-plan) plutôt que de bloquer la réponse.

```mermaid theme={null}
sequenceDiagram
    participant Paps
    participant VotreServeur as Votre serveur
    Paps->>VotreServeur: POST (event StatusUpdated)
    VotreServeur-->>Paps: 200 OK (immédiat)
    VotreServeur->>VotreServeur: Traitement asynchrone de l'événement
```

## Gérer les doublons

Concevez votre endpoint pour qu'il soit idempotent : un même événement reçu plusieurs fois ne doit pas produire d'effet différent. C'est une bonne pratique standard pour tout récepteur de webhook, quel que soit son fournisseur.

## Journaliser les événements

Conservez une trace de chaque événement reçu (horodatage, payload brut, code de réponse renvoyé) pour faciliter le diagnostic en cas d'écart avec l'état observé côté Paps.