# Webhooks (/fr/webhooks)



Les webhooks informent votre serveur des changements dans votre organisation Tapaya. Utilisez la même intégration pour les paiements en magasin et en ligne, quel que soit le processeur de paiement.

## Fonctionnement [#how-it-works]

<WebhookLifecycle senderLabel="Tapaya" receiverLabel="Votre serveur" label="Un changement validé met un événement en file d'attente. Tapaya le signe et l'envoie. Votre récepteur le vérifie et le stocke. Une réponse 2xx confirme la livraison ; les échecs entraînent une nouvelle tentative à partir de l'étape d'envoi, jusqu'à 12 tentatives, puis l'arrêt." event="Changement enregistré" queue="Événement en attente" send="POST signé" receive="Vérifier et stocker" delivered="Livré" />

Configurez une destination HTTPS par organisation et sélectionnez les événements dont vous avez besoin. Tapaya envoie un `POST` HTTP avec un instantané JSON et une signature. Vérifiez la signature, stockez l’événement et renvoyez une réponse de succès avant d’exécuter votre logique métier.

Vous pouvez vous abonner à des types individuels ou à tous les types pris en charge. Un abonnement à tous les types reçoit également les nouveaux types pris en charge à l’avenir ; ignorez donc les types que votre application ne reconnaît pas.

## Intégration rapide [#quick-integration]

<div className="fd-steps [&_h3]:fd-step">
  ### Enregistrer une destination [#save-a-destination]

  Dans la Platform, ouvrez **API Keys**, puis **Webhooks**. Saisissez votre URL HTTPS, choisissez les événements dont vous avez besoin et enregistrez. Copiez dès maintenant le signing secret ; il n’est affiché qu’une seule fois. Consultez la [configuration](/webhooks/configuration).

  ### Vérifier chaque requête [#verify-each-request]

  Calculez un HMAC-SHA256 de l’horodatage, d’un point et du corps brut avec votre signing secret, puis comparez-le à `X-Tapaya-Signature`. Consultez [Vérifier la signature](/webhooks/receiving#check-the-signature).

  ### Stocker l’événement, puis renvoyer 2xx [#store-the-event-then-return-2xx]

  Enregistrez l’événement avec un `id` unique, répondez `2xx` dans les 10 secondes et traitez-le ensuite. Consultez [Stocker et accuser réception](/webhooks/receiving#store-and-acknowledge).

  ### Envoyer un webhook de test [#send-a-test-webhook]

  Sur la même page, utilisez l’action de test pour envoyer un `webhook.test` signé. Consultez [Envoyer un webhook de test](/webhooks/receiving#send-a-test-webhook).
</div>

## Enveloppe des événements [#event-envelope]

Chaque événement utilise cette structure commune. L’instantané de la ressource dans `data` dépend de son type.

```json
{
  "id": "019a0000-0000-7000-8000-000000000001",
  "type": "payment.succeeded",
  "apiVersion": "1",
  "organizationId": "019a0000-0000-7000-8000-000000000002",
  "merchantId": "019a0000-0000-7000-8000-000000000005",
  "createdAt": "2026-10-30T12:00:00.000000Z",
  "data": {
    "payment": {
      "id": "019a0000-0000-7000-8000-000000000003",
      "token": "example_payment_token",
      "merchantId": "019a0000-0000-7000-8000-000000000005",
      "status": "success",
      "statusId": 2,
      "requestedAmount": 10000,
      "requestedCurrencyId": 203,
      "settlementAmount": 10000,
      "settlementCurrencyId": 203
    }
  }
}
```

| Champ            | Signification                                                                                                                                                  |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`             | Identifiant unique de l’événement. Utilisez-le pour dédupliquer les livraisons. Les nouvelles tentatives conservent le même identifiant.                       |
| `type`           | Nom de l’événement dans le [catalogue des événements](/webhooks/events).                                                                                       |
| `apiVersion`     | Identifiant du schéma du payload, actuellement la chaîne `"1"`.                                                                                                |
| `organizationId` | Organisation à laquelle appartient l’événement. Vérifiez qu’elle correspond à votre intégration.                                                               |
| `merchantId`     | Commerçant auquel appartient la ressource. Peut être `null` pour les paiements anciens dont l’appartenance n’est pas déterminée ou pour un test de diagnostic. |
| `createdAt`      | Heure UTC à laquelle l’événement a été enregistré, plutôt que son heure de livraison.                                                                          |
| `data`           | Instantané immuable de la ressource au moment de l’enregistrement de l’événement.                                                                              |

Les montants sont des entiers exprimés dans la plus petite unité de la devise du champ. Par exemple, `10000` avec l’identifiant numérique de devise ISO 4217 `203` correspond à 100,00 CZK. Les montants demandés et les montants de règlement peuvent utiliser des devises différentes.

Chaque type d’événement place son propre instantané dans `data`. Consultez les [types d’événements](/webhooks/events) pour la structure de chaque payload et chaque valeur de statut.

## Règles de livraison [#delivery-rules]

Tapaya envoie un événement dès que son changement est enregistré, et continue de l’envoyer jusqu’à ce que votre serveur réponde `2xx`.

| Règle                | Comportement                                                                                                           |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Accusé de réception  | Toute réponse `2xx` dans les 10 secondes. Les redirections ne sont pas suivies.                                        |
| Nouvelles tentatives | Jusqu’à 12 tentatives sur environ 20 heures, avec des délais de 1, 2, 4, 8, 16, 32, 64, 128, 256, 360 et 360 minutes.  |
| Ordre                | Non garanti. La livraison a lieu au moins une fois : attendez-vous à des doublons et à des instantanés plus anciens.   |
| Simultanéité         | 2 requêtes à la fois par organisation, partagées avec les tests manuels. Les autres événements attendent dans la file. |

Une livraison échouée ne modifie jamais le paiement lui-même, et les livraisons passées ne peuvent pas être renvoyées. Pour vous remettre à jour après une interruption, lisez l’état actuel via les [API de paiements et de commerçants](/platform-api/reporting).

## Commencer l’intégration [#start-integrating]

<Cards>
  <Card title="Configurer une destination" href="/webhooks/configuration">
    Définissez l’URL, choisissez les événements et conservez votre signing secret (secret de signature).
  </Card>

  <Card title="Parcourir les types d'événements" href="/webhooks/events">
    Trouvez le déclencheur exact de chaque événement de paiement, de commerçant et d’onboarding.
  </Card>

  <Card title="Vérifier et tester" href="/webhooks/receiving">
    Validez les signatures et envoyez un webhook de diagnostic.
  </Card>
</Cards>