מעבר לתוכן
Unisoftתיעוד למפתחים

REST API / v2

קבלת Webhooks

קבלו אירועים של Unisoft בשרת שלכם ואמתו את החתימה שלהם.

סביבת התיעוד · ייצורhttps://api.unisoft.world/integrations/v2

במסך ״מפתחים״, הגדירו כתובת יעד מסוג HTTPS ובחרו אילו אירועים לקבל. שמרו את הסוד שמוצג בעת היצירה או החלפת הסוד.

אמתו את חתימת HMAC SHA-256 מול גוף הבקשה הגולמי וחותמת הזמן, לפני קריאת ה-JSON. שמרו את האירוע לפני החזרת סטטוס 2xx, ואז עבדו עליו באופן אסינכרוני.

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

השתמשו במזהה האירוע כדי למנוע עיבוד כפול. משלוחים עשויים לחזור או להגיע בסדר שונה.

הפורמטים, הדוגמאות, הכותרות וכללי הניסיון החוזר מפורטים בחוזה ה-Webhooks שלהלן וב-x-webhooks בקובץ OpenAPI.

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):

{
  "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):

{
  "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.

התיעוד המפורט זמין בצרפתית ובאנגלית. שמות הנתיבים, השדות והערכים הטכניים נשארים ללא שינוי.