**Versions de l’API** · **V2 (Latest)** · [V1](/integrations/v1/docs?lang=fr)

# Recevoir les webhooks

Recevez les événements Unisoft sur votre serveur et vérifiez leur signature.

Dans Développeurs, configurez une destination HTTPS et les événements à recevoir. Conservez le secret affiché lors de la création ou de la rotation.

Vérifiez la signature HMAC SHA-256 sur le corps brut et le timestamp avant de lire le JSON. Enregistrez l’événement avant de répondre avec un statut 2xx, puis traitez-le de façon asynchrone.

```shell
signed_payload = X-Unisoft-Timestamp + "." + raw_body
expected_signature = "sha256=" + HMAC_SHA256_HEX(secret, signed_payload)
```

Utilisez l’identifiant de l’événement pour éviter un traitement en double. Les livraisons peuvent être répétées ou arriver dans un ordre différent.

Les formats, exemples, en-têtes et règles de nouvelle tentative sont détaillés dans le contrat des webhooks ci-dessous et dans x-webhooks du fichier OpenAPI.

## Webhooks de paiement

Unisoft envoie une requête HTTP POST avec Content-Type: application/json à l’URL HTTPS configurée dans Developers > Outbound webhooks. Le secret d’intégration n’est affiché qu’une seule fois, à la création ou à la rotation ; aucune clé API n’est envoyée à votre opération.

Vérifiez `X-Unisoft-Signature` par rapport à `"sha256=" + hex(HMAC-SHA256(secret, X-Unisoft-Timestamp + "." + rawBody))`. Utilisez les octets exacts de la requête brute, AVANT l’analyse du JSON (les fonctions HTTPS Firebase exposent `req.rawBody`). Utilisez une comparaison résistante aux attaques temporelles et rejetez les horodatages non numériques ou obsolètes ; la tolérance recommandée est de 300 secondes. L’horodatage est en secondes Unix et est renouvelé à chaque tentative.

Accusez réception avec n’importe quelle réponse 2xx dans les 10 secondes ; le corps de la réponse est ignoré. Enregistrez l’événement ou placez-le en file avant l’accusé de réception, puis traitez-le de façon asynchrone. Dédupliquez par l’identifiant de l’enveloppe (également `X-Unisoft-Event-Id`) ; il reste stable lors des nouvelles tentatives de livraison, tandis que `attempt` augmente. `createdAt` est la date de mise en file, pas nécessairement la date du paiement. Les livraisons peuvent être dupliquées ou arriver dans le désordre.

Les erreurs réseau, délais d’attente dépassés, réponses 5xx, 408 et 429 entraînent de nouvelles tentatives, jusqu’à 6. Les autres réponses 4xx sont définitives. Après 20 échecs consécutifs de l’intégration, la destination est mise en quarantaine pendant 24 heures. La livraison n’est pas garantie sans limite ; rapprochez les données avec GET /paiements si nécessaire.

Les données de paiement sont un instantané du paiement au moment de l’émission, et non un événement bancaire normalisé. `amount` est exprimé en unités mineures, `devise` indique la devise, `contact` est un identifiant de contact (pas un objet contact) et `info` contient l’identité du donateur. Les champs supplémentaires varient selon le fournisseur et le type. `externalRef` et `externalMetadata` sont inclus s’ils existent ; les anciens paiements peuvent ne pas les contenir. Ne vous fiez pas aux champs propres à un fournisseur. Ces charges utiles peuvent contenir des données personnelles.

### paiement.success / paiement.refunded

Abonnez-vous à paiement.success pour les paiements terminés et à paiement.refunded pour les remboursements confirmés. Les notifications de remboursement contiennent le paiement d’origine avec son état de remboursement mis à jour ; `amount` conserve le montant du paiement d’origine. La réponse synchrone de l’API de remboursement est un objet différent.

Exemple de paiement.success (champs représentatifs ; des champs propres au fournisseur peuvent également être présents) :

```json
{
  "id": "800efee9-9414-4392-98d0-2ebf6759f617",
  "type": "paiement.success",
  "organisation": "org_example",
  "createdAt": "2026-10-16T11:00:00.000Z",
  "attempt": 1,
  "data": {
    "id": "cf161b09-6bab-4a24-9c7b-c8f223b18c09",
    "organisation": "org_example",
    "name": "Donation",
    "state": "COMPLETED",
    "type": "GENERAL",
    "platform": "STRIPE",
    "method": "CB",
    "amount": 1500,
    "devise": "eur",
    "contact": "contact_example",
    "info": {
      "prenom": "Sarah",
      "nom": "Cohen",
      "email": "sarah@example.org",
      "tel": ""
    },
    "datetime": "2026-10-16T10:00:00.000Z",
    "externalRef": "commande-1234",
    "externalMetadata": {
      "registrationId": "inscription-567",
      "eventId": "chabbat-890"
    }
  }
}
```

Exemple de paiement.refunded (champs représentatifs ; des champs propres au fournisseur peuvent également être présents) :

```json
{
  "id": "800efee9-9414-4392-98d0-2ebf6759f617",
  "type": "paiement.refunded",
  "organisation": "org_example",
  "createdAt": "2026-10-16T11:00:00.000Z",
  "attempt": 1,
  "data": {
    "id": "cf161b09-6bab-4a24-9c7b-c8f223b18c09",
    "organisation": "org_example",
    "name": "Donation",
    "state": "REFUNDED",
    "type": "GENERAL",
    "platform": "STRIPE",
    "method": "CB",
    "amount": 1500,
    "devise": "eur",
    "contact": "contact_example",
    "info": {
      "prenom": "Sarah",
      "nom": "Cohen",
      "email": "sarah@example.org",
      "tel": ""
    },
    "datetime": "2026-10-16T10:00:00.000Z",
    "externalRef": "commande-1234",
    "externalMetadata": {
      "registrationId": "inscription-567",
      "eventId": "chabbat-890"
    },
    "refund": {
      "state": "SUCCEEDED",
      "reason": "requested_by_customer",
      "updatedAt": "2026-10-16T11:00:00.000Z"
    }
  }
}
```

### En-têtes

| En-tête | Signification |
|---|---|
| X-Unisoft-Event | Identique à body.type |
| X-Unisoft-Event-Id | Identique à body.id ; clé de déduplication |
| X-Unisoft-Delivery-Id | Identifiant de l’enregistrement de livraison pour cette destination |
| X-Unisoft-Timestamp | Secondes Unix |
| X-Unisoft-Signature | sha256= suivi du HMAC en hexadécimal minuscule |

### Test de connectivité

Le bouton Test du back-office envoie webhook.test via la file signée habituelle, indépendamment de la liste des événements auxquels vous êtes abonné. Il ne crée aucun paiement ni remboursement. Ses données contiennent `test:true`, `triggeredBy` (identifiant d’accès administrateur ou null) et `message`. Des schémas lisibles par machine propres à chaque événement sont également disponibles sous `x-webhooks` dans openapi.json.
