{"templateId":"openapi_docs","sharedDataIds":{"openAPIDocsStore":"oas-api/ClientAPI.json","sidebar":"sidebar-sidebar.yaml__api_clientapi"},"props":{"definitionId":"api/ClientAPI.json","dynamicMarkdocComponents":[],"baseSlug":"/api/clientapi","seo":{"title":"Webhook subscriptions","description":"**1. WHAT IS A WEBHOOK ?**\n\n - Webhooks are events based real-time notifications providing updates on transactions and removing the need for periodic polling.\n\n - Webhook notifications are sent as HTTPS POST requests to a URL of your choice.\n\n**2. WEBHOOK SUBSCRIPTIONS**\n\n - Each webhook subscription allows you to receive notifications for one or more event types :\n\n   -  **Outgoing payment :**`PAYMENT_PLANIFIED` `PAYMENT_FINALIZED` `PAYMENT_WAITING_SIGNATURE` `PAYMENT_AWAITING_CONFIRMATION` `PAYMENT_CANCELED` `PAYMENT_BLOCKED` `PAYMENT_WAITING_JUSTIFICATION` `PAYMENT_INCOMING`\n\n   -  **Spot trade** : `TRADE_PLANIFIED` `TRADE_FINALIZED` `TRADE_CANCELED` `TRADE_BLOCKED`\n\n   -  **Fixed forward payment contract** : `FIXED_FORWARD_PLANIFIED` `FIXED_FORWARD_FINALIZED` `FIXED_FORWARD_CANCELED`\n\n - You may have up to 10 active subscriptions at the same time.\n\n **3. IMPLEMENTATION**\n\n - **Delivery and retries**\n   -  Webhook notifications may not be delivered in order, your implementation should not assume sequential delivery.\n   - 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.\n - **Acknowledgement**\n   - We recommend responding with a HTTP `204` code (No Content) to acknowledge receipt of a notification.\n  - **Whitelisting**\n    - To ensure webhook notifications reach your URL, you may need to whitelist the following IP (production and demo): **51.158.86.1**. \n\n**4. SECURITY**\n\n- Each webhook notification includes an HMAC-256 signature in the request header to let you **validate its authenticity**.\n  -  To verify the signature, recontruct the signed message by concatenating the exact timestamp and request raw body as received : `x-ibanfirst-timestamp.{Body}`.\n    - 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.\n    - You must **reject** the notification if the signatures do not match.\n -  Recommended best practices :\n    - Always validate the signature before processing any webhook notification.\n    - Webhook notification payloads must be stored on a private server to protect sensitive data.\n\n**5. WEBHOOK NOTIFICATION CONTENT**\n\n Notifications contain the relevant object as described in each reconciliation service.\n - [Get payment details](https://docs.ibanfirst.com/api/clientapi/payments/paths/~1payments~1%7Bid%7D/get)\n - [Get trade detail](https://docs.ibanfirst.com/api/clientapi/trades/paths/~1trades~1%7Bid%7D/get)\n - [Get fixed forward details](https://docs.ibanfirst.com/api/clientapi/spot-trades/paths/~1trades~1%7Bid%7D/get)\n\n```json\n{\n \"event\": event_label,\n \"payload\": {\n    see get payment details, get trade details or get fixed forward details\n },\n\"webhookId\": \"e35b6e8d-67ef-4973-945d-c3190a60d0aa\"\n}\n```"},"itemId":"webhook-subscriptions","disableAutoScroll":true,"metadata":{},"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"headers":{"accept":"*/*","accept-encoding":"gzip, br, zstd, deflate","host":"docs.ibanfirst.com","user-agent":"Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)","via":"2.0 Caddy, 2.0 44147ec36a13b8400f9afbf3bfc1f8d8.cloudfront.net (CloudFront), 1.1 Caddy","x-amz-cf-id":"MJEBeqaON1x-6gYT0Pajgd5VuqhP-PLsqlyVuMwI6LWnYMUl4xU2mg==","x-forwarded-for":"216.73.216.127, 3.211.34.228, 15.158.215.79","x-forwarded-host":"docs.ibanfirst.com","x-forwarded-proto":"https","x-request-id":"cds-4330184d-f94c-47b8-b56b-af2dc45adf44"},"remoteAddr":{"hostname":"::ffff:10.0.1.248","port":47626},"lang":"default_locale"}}},"slug":"/api/clientapi/webhook-subscriptions","userData":{"isAuthenticated":false,"teams":["anonymous"]}}