**API versions** · [V2 (Latest)](/integrations/v2/docs?lang=en) · **V1**

> **This API version is obsolete.** Use the latest version for new integrations. [View the current documentation](/integrations/v2/docs?lang=en)

# Receiving webhooks

Receive Unisoft events on your server and verify their signatures.

In Developers, configure an HTTPS destination and select the events to receive. Save the secret shown when the destination is created or the secret is rotated.

Verify the HMAC SHA-256 signature against the raw body and timestamp before reading the JSON. Store the event before responding with a 2xx status, then process it asynchronously.

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

Use the event ID to prevent duplicate processing. Deliveries may be repeated or arrive out of order.

Formats, examples, headers, and retry rules are detailed in the webhook contract below and in x-webhooks in the OpenAPI file.

## Payment webhooks

Unisoft sends an HTTP POST with Content-Type: application/json to the HTTPS URL configured in Developers > Outbound webhooks. The integration secret is shown once at creation/rotation; no API key is sent to your endpoint.

Verify X-Unisoft-Signature against "sha256=" + hex(HMAC-SHA256(secret, X-Unisoft-Timestamp + "." + rawBody)). Use the exact raw request bytes, BEFORE parsing JSON (Firebase HTTPS functions expose req.rawBody). Use a timing-safe comparison and reject non-numeric or stale timestamps; recommended tolerance is 300 seconds. The timestamp is Unix seconds and is refreshed for each attempt.

Acknowledge with any 2xx response within 10 seconds; the response body is ignored. Persist/enqueue the event before acknowledging, then process asynchronously. Deduplicate by the envelope id (also X-Unisoft-Event-Id); it stays stable across delivery retries, while attempt increases. createdAt is the enqueue date, not necessarily the payment datetime. Deliveries may be duplicated or arrive out of order.

Network errors, timeouts, 5xx, 408 and 429 are retried, up to 6 attempts. Other 4xx are terminal. After 20 consecutive integration failures the destination is quarantined for 24 hours. This is not an unlimited delivery guarantee; reconcile with GET /paiements when needed.

Payment data is a snapshot of the payment at emission, not a normalized bank event. amount is in minor units, devise is the currency, contact is a contact ID (not a contact object), and info holds donor identity. Additional fields vary by provider/type. externalRef and externalMetadata are included when present; old payments may omit them. Do not rely on provider-specific fields. These payloads can contain personal data.

### paiement.success / paiement.refunded

Subscribe to paiement.success for completed payments and paiement.refunded for confirmed refunds. Refund notifications contain the original payment with its updated refund state; amount remains the original payment amount. The synchronous refund API response is a different object.

Example paiement.success (representative fields; provider-specific fields may also be present):

```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"
    }
  }
}
```

Example paiement.refunded (representative fields; provider-specific fields may also be present):

```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"
    }
  }
}
```

### Headers

| Header | Meaning |
|---|---|
| X-Unisoft-Event | Same as body.type |
| X-Unisoft-Event-Id | Same as body.id; deduplication key |
| X-Unisoft-Delivery-Id | Delivery record ID for this destination |
| X-Unisoft-Timestamp | Unix seconds |
| X-Unisoft-Signature | sha256= followed by the lowercase hex HMAC |

### Connectivity test

The backoffice Test button sends webhook.test through the normal signed queue, regardless of the subscription event list. It creates no payment or refund. Its data contains test:true, triggeredBy (admin access ID or null) and message. Event-specific machine-readable schemas are also available under x-webhooks in openapi.json.
