# iBanFirst Webhook subscriptions API

**Canonical:** https://apis.io/apis/ibanfirst/ibanfirst-webhook-subscriptions-api/  
**Provider:** iBanFirst — https://apis.io/providers/ibanfirst/  
**Base URL:** https://api.ibanfirst.com/api  
**Documentation:** https://docs.ibanfirst.com/api/clientapi

iBanFirst Webhook subscriptions API is one of 11 APIs that [iBanFirst](https://apis.io/providers/ibanfirst/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. Tagged areas include Webhook Subscriptions. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, an API reference, a getting-started guide, and authentication docs.

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

## Operations (7)

| Method | Path | Summary |
|---|---|---|
| POST | `/webhooks` | Create webhook subscription |
| GET | `/webhooks` | Get webhook subscriptions list |
| GET | `/webhooks/{webhookId}` | Get webhook subscription details |
| PATCH | `/webhooks/{webhookId}` | Update webhook subscription |
| DELETE | `/webhooks/{webhookId}` | Cancel webhook subscription |
| POST | `/webhooks/{webhookId}/rotate-secret` | Rotate secret |
| GET | `/webhooks/{webhookId}/failed-notifications` | Get failed notifications |

## Machine-readable artifacts (12)

- **OpenAPI** — https://raw.githubusercontent.com/api-evangelist/ibanfirst/refs/heads/main/openapi/ibanfirst-webhook-subscriptions-api-openapi.yml
- **Documentation** — https://docs.ibanfirst.com/
- **APIReference** — https://docs.ibanfirst.com/api/clientapi
- **GettingStarted** — https://docs.ibanfirst.com/guides/quickstart
- **Postman** — https://www.postman.com/productibf/ibanfirst-rest-api-workspace/collection/d24hl8d/ibanfirst-rest-api
- **Authentication** — https://raw.githubusercontent.com/api-evangelist/ibanfirst/refs/heads/main/authentication/ibanfirst-authentication.yml
- **Conventions** — https://raw.githubusercontent.com/api-evangelist/ibanfirst/refs/heads/main/conventions/ibanfirst-conventions.yml
- **ErrorCatalog** — https://raw.githubusercontent.com/api-evangelist/ibanfirst/refs/heads/main/errors/ibanfirst-problem-types.yml
- **DataModel** — https://raw.githubusercontent.com/api-evangelist/ibanfirst/refs/heads/main/data-model/ibanfirst-data-model.yml
- **Webhooks** — https://raw.githubusercontent.com/api-evangelist/ibanfirst/refs/heads/main/asyncapi/ibanfirst-webhooks.yml
- **Sandbox** — https://raw.githubusercontent.com/api-evangelist/ibanfirst/refs/heads/main/sandbox/ibanfirst-sandbox.yml
- **Glossary** — https://docs.ibanfirst.com/glossary

## Other iBanFirst APIs (10)

- [iBanFirst MCP Connector](https://apis.io/apis/ibanfirst/ibanfirst-mcp-connector/)
- [iBanFirst PSD2 XS2A API](https://apis.io/apis/ibanfirst/ibanfirst-psd2-xs2a-api/)
- [iBanFirst Accounts API](https://apis.io/apis/ibanfirst/ibanfirst-accounts-api/)
- [iBanFirst Beneficiaries API](https://apis.io/apis/ibanfirst/ibanfirst-beneficiaries-api/)
- [iBanFirst Documents API](https://apis.io/apis/ibanfirst/ibanfirst-documents-api/)
- [iBanFirst Financial movements API](https://apis.io/apis/ibanfirst/ibanfirst-financial-movements-api/)
- [iBanFirst Fixed forward payment contract API](https://apis.io/apis/ibanfirst/ibanfirst-fixed-forward-payment-contract-api/)
- [iBanFirst Logs API](https://apis.io/apis/ibanfirst/ibanfirst-logs-api/)
- [iBanFirst Payments API](https://apis.io/apis/ibanfirst/ibanfirst-payments-api/)
- [iBanFirst Spot trades API](https://apis.io/apis/ibanfirst/ibanfirst-spot-trades-api/)

## Tags

Webhook Subscriptions

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/ibanfirst/ibanfirst-webhook-subscriptions-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/ibanfirst/.