# Notifications

## Create a new notification subscription

 - [POST /v1/notifications/subscriptions](https://developers.bcb.bm/apis/open-banking-api/open-banking-api/notifications/notifications_create.md): Registers a webhook subscription to receive real-time deposit notifications.

### Notification Pipeline Overview:
This endpoint is part of a two-stage deposit notification system:

Stage 1: Subscription Setup (this endpoint)
- Customers register their webhook URL and topic (e.g., "Deposits")
- The system stores the subscription with optional custom headers
- Subscriptions can be activated or deactivated

Stage 2: Webhook Delivery
- The system matches received events with active subscriptions
- Webhooks are delivered to registered endpoints with retry logic

### Webhook Payload Structure:
When a deposit matches your subscription, you'll receive a POST request to your webhook URL containing:
json
{
  "subscriptionId": "e2a55504-3924-4b48-9d7e-540efcd6fa30",
  "topic": "Deposits",
  "accountNumber": "1046406142",
  "transactionId": "FT2384654NXF6",
  "type": "Credit",
  "value": {
    "amount": "1000.00",
    "currency": "USD"
  },
  "transactionType": "Swift payment",
  "transactionDetails": "Payment details"
}


The webhook payload is defined by the NotificationResponse model.

### Message Signing:
Webhook requests are signed for authenticity and replay protection.
- Asymmetric option (RSA-PSS + SHA-256): When response signing is enabled for your client configuration, webhooks include Bcb-Signature, Bcb-Timestamp, Bcb-Nonce, and Bcb-Signature-Version (e.g., rsa-v1). Verify using the bank public key from /v1/.well-known/jwks.json and the canonical string {timestamp}{nonce}{METHOD}{path}{body}.
- HMAC option: If Bcb-Signature-Version is absent, the webhook uses your Message Signing Secret returned by the credentials endpoints. Use the same signature string {timestamp}{nonce}{METHOD}{path}{body} and compare an HMAC-SHA256 hash.
- Replay protection: Enforce ±5 minute timestamp tolerance and reject any repeated {timestamp}:{nonce} pairs (cache the nonce for 5 minutes).
See the Message Signing guide for full RSA and HMAC verification examples.

### Idempotency:
This endpoint supports idempotency through the optional Idempotency-Key header:
- If no idempotency key is provided, the request is processed normally
- If a valid UUID idempotency key is provided, the system prevents duplicate subscriptions
- The idempotency key must be a valid UUID format (e.g., "123e4567-e89b-12d3-a456-426614174000")

Required Permission: receive-notifications

This endpoint requires the permission claim receive-notifications to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.

## List subscriptions

 - [GET /v1/notifications/subscriptions](https://developers.bcb.bm/apis/open-banking-api/open-banking-api/notifications/notifications_getall.md): Retrieves all notification subscriptions for the authenticated client with pagination support.

### Pagination:
- Use pageStart to specify the starting page (default: 1)
- Use pageSize to specify the number of items per page (default: 100, max: 500)
- The response includes total count and pagination metadata

### Response Details:
Returns a paginated list of subscriptions, each containing:
- Subscription ID (guid)
- Topic (e.g., "Deposits")
- Webhook URL
- Status (IsActive flag)
- Creation and update timestamps

### Filtering:
- Only returns subscriptions owned by the authenticated client
- Includes both active and inactive subscriptions
- Results are ordered by creation date (newest first)

Required Permission: receive-notifications

This endpoint requires the permission claim receive-notifications to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.

## Deactivate a subscription

 - [DELETE /v1/notifications/subscriptions/{subscriptionId}](https://developers.bcb.bm/apis/open-banking-api/open-banking-api/notifications/notifications_delete.md): Deactivates an existing notification subscription. Once deactivated:
- The subscription will no longer receive webhook notifications
- Future deposits will not be matched to this subscription
- In-flight notifications will continue to be delivered
- The subscription record remains in the system but with IsActive=false

### Behavior:
- Only the subscription owner can deactivate their own subscription
- Attempting to deactivate another client's subscription returns 404 Not Found
- Deactivating an already inactive subscription is idempotent (returns success)

### Idempotency:
This endpoint supports idempotency through the optional Idempotency-Key header:
- If a valid UUID idempotency key is provided, repeated calls with the same key return the same result
- The idempotency key must be a valid UUID format (e.g., "123e4567-e89b-12d3-a456-426614174000")

Required Permission: receive-notifications

This endpoint requires the permission claim receive-notifications to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.

## Get subscription

 - [GET /v1/notifications/subscriptions/{subscriptionId}](https://developers.bcb.bm/apis/open-banking-api/open-banking-api/notifications/notifications_get.md): Retrieves a specific notification subscription by its unique identifier.

### Response Details:
The response includes:
- Subscription ID (guid)
- Topic (e.g., "Deposits")
- Webhook URL
- Status (IsActive flag)
- Creation and update timestamps
- Client association

### Security:
- Only the subscription owner can retrieve their own subscription
- Attempting to retrieve another client's subscription returns 404 Not Found

Required Permission: receive-notifications

This endpoint requires the permission claim receive-notifications to be present in the JWT token. These permissions are embedded in the token during the authentication process and cannot be modified afterward. The token must be obtained with the appropriate permissions to access this endpoint.