iBanFirst Webhook subscriptions API

**1. WHAT IS A WEBHOOK ?** - Webhooks are events based real-time notifications providing updates on transactions and removing the need for periodic polling. - Webhook notifications are sent as HTTPS POST requests to a URL of your choice.**2. WEBHOOK SUBSCRIPTIONS** - Each webhook subscription allows you to receive notifications for one or more event types : - **Outgoing payment :**`PAYMENT_PLANIFIED` `PAYMENT_FINALIZED` `PAYMENT_WAITING_SIGNATURE` `PAYMENT_AWAITING_CONFIRMATION` `PAYMENT_CANCELED` `PAYMENT_BLOCKED` `PAYMENT_WAITING_JUSTIFICATION` `PAYMENT_INCOMING` - **Spot trade** : `TRADE_PLANIFIED` `TRADE_FINALIZED` `TRADE_CANCELED` `TRADE_BLOCKED` - You may have up to 10 active subscriptions at the same time. **3. IMPLEMENTATION** - **Delivery and retries** - Webhook notifications may not be delivered in order, your implementation should not assume sequential delivery. - If a notification delivery fails (HTTP status code 400 or 500), it will be retried twice, with a 60-second delay between attempts. This results in a maximum of three delivery attempts per event. - **Acknowledgement** - We recommend responding with a HTTP `204` code (No Content) to acknowledge receipt of a notification. - **Whitelisting** - To ensure webhook notifications reach your URL, you may need to whitelist the following IP (production and demo): **51.158.86.1**. **4. SECURITY**- Each webhook notification includes an HMAC-256 signature in the request header to let you **validate its authenticity**. - To verify the signature, recontruct the signed message by concatenating the exact timestamp and request raw body as received : `x-ibanfirst-timestamp.{Body}`. - Compute an HMAC-SHA256 hash of this string using the subscription secret key and compare the result with the `x-ibanfirst-signature` provided in the notification header. - You must **reject** the notification if the signatures do not match. - Recommended best practices : - Always validate the signature before processing any webhook notification. - Webhook notification payloads must be stored on a private server to protect sensitive data.**5. WEBHOOK NOTIFICATION CONTENT** Notifications contain the relevant object as described in each reconciliation service. - [Get payment details](https://docs.ibanfirst.com/api/clientapi/payments/paths/~1payments~1%7Bid%7D/get) - [Get trade detail](https://docs.ibanfirst.com/api/clientapi/trades/paths/~1trades~1%7Bid%7D/get)```json{ "event": event_label, "payload": { see get payment details, get trade details },"webhookId": "e35b6e8d-67ef-4973-945d-c3190a60d0aa"}```