# Configuration (/fr/webhooks/configuration)





Chaque organisation possède une destination de webhook et un signing secret (secret de signature) actif. Configurez-les dans la Platform ou depuis votre serveur.

| Détail           | Valeur                                                                                                |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| URL de base      | `https://api.sandbox.tapaya.com` pour la sandbox, `https://api.tapaya.com` pour la production         |
| Authentification | Server Secret Token dans `Authorization`. Consultez [Authentification](/platform-api#authentication). |
| Portée           | Une destination par organisation                                                                      |
| Guide associé    | [Vérifier et tester](/webhooks/receiving)                                                             |

## Configurer dans la Platform [#configure-in-the-platform]

Ouvrez [API Keys](https://platform.tapaya.com/api-keys/) pour votre organisation et recherchez **Webhooks**.

1. Saisissez votre URL HTTPS publique.
2. Choisissez les événements dont vous avez besoin, ou activez **Subscribe to all webhook types**.
3. Activez **Enable** et cliquez sur **Save**.
4. Copiez le signing secret et stockez-le sur votre serveur.
5. Envoyez un [webhook de test](/webhooks/receiving#send-a-test-webhook).

<Callout type="warn" title="Le signing secret n’est affiché qu’une seule fois">
  Copiez-le lorsque vous créez la destination ou renouvelez son secret ; il ne pourra pas être récupéré ultérieurement. Il sert uniquement à vérifier les webhooks entrants. Votre Server Secret Token autorise les requêtes de configuration.
</Callout>

## Toutes les opérations [#all-operations]

| Opération                                          | À utiliser pour                                                                    |
| -------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [Enregistrer une destination](#save-a-destination) | Créer ou remplacer l’abonnement actuel, ou renouveler son signing secret.          |
| [Lire une destination](#read-a-destination)        | Récupérer l’URL actuelle, le mode d’abonnement et l’état d’activation.             |
| [Supprimer une destination](#delete-a-destination) | Supprimer l’abonnement ainsi que sa file d’attente et son historique de livraison. |

## Gérer la destination [#manage-the-destination]

<Accordions type="multiple">
  <Accordion title="Enregistrer une destination" id="save-a-destination">
    **À utiliser pour** connecter votre récepteur HTTPS et choisir les événements à livrer.

    ```bash
    curl --request PUT \
      'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME' \
      --header 'Content-Type: application/json' \
      --data '{
        "url": "https://payments.example.com/webhooks/tapaya",
        "eventTypes": ["payment.succeeded", "payment.failed", "payment.refund.succeeded"],
        "subscribeAllEventTypes": false,
        "enabled": true,
        "rotateSecret": false
      }'
    ```

    **Bon à savoir :**

    * Cela remplace la configuration enregistrée ; aucun second endpoint n’est ajouté.
    * La création et le renouvellement explicite renvoient `{"signingSecret":"twhsec_..."}`. Une mise à jour ordinaire renvoie `{"signingSecret":null}`.
    * Conservez l’intégralité du secret renvoyé, y compris son préfixe. Il n’est jamais renvoyé par GET.
    * Votre jeton détermine l’organisation ; n’envoyez pas d’identifiant d’organisation.

    **Paramètres :**

    | Champ                    | Obligatoire | Signification                                                                                                                                              |
    | ------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `url`                    | Oui         | URL HTTPS publique sur le port 443, de 2 048 caractères au maximum, sans identifiants intégrés ni fragment.                                                |
    | `eventTypes`             | Oui         | Tableau de noms issus du [catalogue](/webhooks/events). Choisissez-en au moins un, sauf si vous vous abonnez à tous les types.                             |
    | `subscribeAllEventTypes` | Non         | Vaut `false` par défaut. Définissez `true` avec `eventTypes: []` pour inclure tous les types actuellement pris en charge et ceux qui le seront à l’avenir. |
    | `enabled`                | Oui         | Enregistre les nouveaux événements correspondants et envoie les événements en attente lorsque la valeur est `true`.                                        |
    | `rotateSecret`           | Oui         | Génère et renvoie un nouveau signing secret lorsque la valeur est `true`.                                                                                  |
  </Accordion>

  <Accordion title="Lire une destination" id="read-a-destination">
    **À utiliser pour** examiner l’abonnement enregistré sans révéler son signing secret.

    ```bash
    curl 'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME'
    ```

    **Bon à savoir :**

    * GET renvoie `404` lorsque cette organisation n’a pas de destination.
    * Les abonnements à tous les types renvoient un tableau `eventTypes` vide avec `subscribeAllEventTypes: true`.
    * La réponse ne contient jamais le signing secret.
    * Utilisez `availableEventTypes` pour créer un sélecteur d’événements sans coder le catalogue en dur.

    **Réponse :**

    | Champ                    | Signification                                                            |
    | ------------------------ | ------------------------------------------------------------------------ |
    | `url`                    | Destination HTTPS enregistrée.                                           |
    | `eventTypes`             | Abonnements explicites, ou tableau vide en mode tous types.              |
    | `subscribeAllEventTypes` | Indique si les types actuels et futurs pris en charge sont sélectionnés. |
    | `enabled`                | Indique si les webhooks sont activés.                                    |
    | `availableEventTypes`    | Tous les noms d’événements auxquels vous pouvez vous abonner.            |
  </Accordion>

  <Accordion title="Supprimer une destination" id="delete-a-destination">
    **À utiliser pour** déconnecter l’organisation et supprimer ses livraisons en attente et son historique de livraison.

    ```bash
    curl --request DELETE \
      'https://api.sandbox.tapaya.com/integrator/organization/webhook' \
      --header 'Authorization: REPLACE_ME'
    ```

    **Bon à savoir :**

    * En cas de succès, la réponse est HTTP `204`, sans corps de réponse.
    * Une requête déjà en cours peut encore arriver après la suppression.
    * Recréer la destination génère un nouveau signing secret et ne restaure pas les événements supprimés.
  </Accordion>
</Accordions>

## Règles de la destination [#configuration]

### Modifier les paramètres [#configuration-changes]

| Lorsque vous                                | Ce qui se passe                                                                                                                                                                                                              |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Modifiez l’URL, les événements ou le secret | Les nouveaux événements utilisent les nouveaux paramètres. Les événements en attente conservent l’ancienne URL et l’ancien secret : gardez-les tous deux fonctionnels jusqu’à ce que la file d’attente soit vidée.           |
| Désactivez les webhooks                     | Les livraisons en attente sont suspendues et aucun nouvel événement n’est enregistré. La réactivation reprend le traitement de la file, mais les changements manqués ne sont pas rattrapés. Les tests fonctionnent toujours. |
| Supprimez la destination                    | Les événements en attente et l’historique de livraison sont supprimés. Une requête déjà en cours peut encore arriver. La recréer génère un nouveau signing secret.                                                           |

### Exigences relatives à l’URL [#destination-requirements]

* HTTPS public sur le port 443. Localhost et les réseaux privés sont rejetés, et le DNS est vérifié à nouveau à chaque connexion.
* Aucun identifiant intégré, aucun fragment et aucune redirection.
* Aucun en-tête d’autorisation personnalisé. Vérifiez plutôt la signature Tapaya, ou placez un adaptateur côté serveur devant une URL qui exige sa propre clé.

## Erreurs [#errors]

Les requêtes de configuration échouent avec ces réponses. Un récepteur qui refuse ou manque une livraison est un problème différent ; consultez [Gérer les erreurs](/webhooks/receiving#handle-errors).

| Réponse       | Signification                                                                                                           |
| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `400` sur PUT | URL invalide, type d’événement non pris en charge, champ obligatoire manquant ou sélection explicite d’événements vide. |
| `401`         | Le Server Secret Token est manquant ou invalide.                                                                        |
| `404` sur GET | Aucune destination n’existe pour l’organisation authentifiée.                                                           |

Poursuivez avec la [vérification des signatures et le test de livraison](/webhooks/receiving).