Alerts & Notifications | Citi Docs Demo

Overview

The Alerts & Notifications API keeps customers informed in real time. Customers choose which events matter to them — a large purchase, a low balance, a completed payment, a new sign-in — and how they want to be notified. Your app receives events via webhooks and can also manage each customer’s preferences.

What you can do

Manage preferences — Let customers turn specific alerts on or off and pick their channel.

Receive events — Subscribe a webhook to get notified the moment an event occurs.

Deliver in real time — Push timely, relevant messages that build trust and engagement.

Alert types

Event	Triggered when
`balance.low`	Available balance falls below the customer’s threshold
`transaction.posted`	A transaction posts to the account
`card.large_purchase`	A purchase exceeds the customer’s set amount
`payment.completed`	A payment or transfer is delivered
`security.new_signin`	A sign-in occurs from a new device

Authenticate

Obtain an access token. See the Authentication guide.

Set the customer's preferences

Enable the alert types the customer wants and set thresholds, such as a low-balance amount.

Register a webhook

Provide an HTTPS endpoint to receive event payloads.

Verify and process

Validate the signature on each delivery, then update your app or notify the customer.

{
  "event": "card.large_purchase",
  "cardRef": "card_44127",
  "data": {
    "amount": 640.00,
    "currency": "USD",
    "merchant": "Best Buy",
    "occurredAt": "2026-04-23T15:02:00Z"
  }
}

Every webhook delivery is signed. Verify the signature header before trusting a payload, and respond with 200 OK quickly — do heavy processing asynchronously.

Delivery channels

Channel	Description
`PUSH`	Mobile push notification
`SMS`	Text message
`EMAIL`	Email notification
`WEBHOOK`	Server-to-server event delivery to your app

Security alerts such as security.new_signin are always delivered and cannot be disabled by the customer, to help protect their account.

Security requirements

Requests require an OAuth 2.0 access token. Webhook payloads are signed and must be verified. See the Authentication guide.