Cobre's FX Rate Alerts API provides a real-time notification mechanism that enables clients to monitor foreign exchange rate movements and receive instant alerts when market conditions meet predefined thresholds.

This feature empowers treasury and finance teams to capture favorable market opportunities, manage currency risk proactively, and optimize cross-border payment timing by automating FX rate monitoring across multiple currency pairs.

FX Rate Alerts follow a clear lifecycle driven by configurable conditions, real-time monitoring, and webhook notifications, ensuring clients never miss critical market movements.

Creating FX Rate Alerts

Clients create FX Rate Alerts by defining monitoring conditions for specific currency pairs. Once an alert is active, Cobre's platform continuously monitors real-time FX rates and triggers notifications when conditions are met.

Supported Alert Conditions:

Above: Trigger when the FX rate exceeds a maximum threshold

Below: Trigger when the FX rate falls below a minimum threshold

Within Range: Trigger when the FX rate enters a specified range

To receive alert notifications, clients must subscribe to the event:

alerts.fx_rate.triggered – Notification when an alert condition is met

Once subscribed, clients will receive a webhook every time an alert is triggered.

FX Rate Alerts Lifecycle

Creation
Client creates an alert via POST /v1/alerts with condition parameters and expiration date.

Active Monitoring
Cobre monitors real-time FX rates for all active alerts (active_status: true).

Trigger Event
When the market rate meets the alert condition, a webhook is sent with the triggering FX rate.

Deactivation
Clients can deactivate alerts via DELETE /v1/alerts/{id}, which sets active_status: false.

Deactivated alerts remain in the system for audit purposes but will not trigger notifications. Alerts also automatically expire based on their valid_until date.

Alert Trigger Notification

Clients receive alert notifications through the Notifications API when subscribed to alerts.fx_rate.triggered. More info: Notifications & Subscriptions

Alert Metadata

The metadata object contains the alert configuration and the triggering FX rate when applicable.

Metadata Fields

Field	Description
`currency_pair`	Currency pair being monitored (e.g., `usd/cop`, `usd/mxn`)
`condition`	Alert condition type: `above`, `below`, or `within_range`
`max_rate`	Maximum rate threshold (used for `above` and `within_range` conditions)
`min_rate`	Minimum rate threshold (used for `below` and `within_range` conditions)
`fx_rate`	The actual FX rate that triggered the alert (only present in trigger notifications)

The fx_rate field is only included in alerts.fx_rate.triggered webhook payloads and represents the market rate at the moment the alert condition was met.

Alert Conditions Catalog

Alerts can be configured with three different condition types depending on your monitoring strategy.

Above Condition

Below Condition

Within Range Condition

Trigger Logic: Alert fires when current_rate > max_rate

Use Case: Notify when a currency strengthens beyond a threshold

Required Fields:

condition: "above"

max_rate: Numeric threshold

Example:

{
  "metadata": {
    "condition": "above",
    "currency_pair": "usd/cop",
    "max_rate": 3500
  }
}

Request Schema for Creating Alerts

When creating a new FX Rate Alert, submit the following payload:

{
  "type": "fx_rate",
  "alias": "My Alert Name",
  "metadata": {
    "condition": "above|below|within_range",
    "currency_pair": "usd/cop",
    "max_rate": 3500,
    "min_rate": 3400
  },
  "valid_until": "2026-12-31T23:59:59Z"
}

Field Descriptions

Field	Type	Required	Description
`type`	string	Yes	Must be `"fx_rate"`
`alias`	string	No	Friendly name for the alert
`metadata.condition`	string	Yes	One of: `above`, `below`, `within_range`
`metadata.currency_pair`	string	Yes	Currency pair to monitor (e.g., `usd/cop`)
`metadata.max_rate`	number	Conditional	Required for `above` and `within_range`
`metadata.min_rate`	number	Conditional	Required for `below` and `within_range`
`valid_until`	string	Yes	ISO 8601 timestamp - alert expiration date

Best Practices

Alert Configuration

Set realistic thresholds based on historical volatility and your execution windows

Use within_range conditions for opportunistic execution strategies

Set appropriate valid_until dates to avoid stale alerts accumulating

Webhook Handling

Implement idempotency checks using the event_id to handle duplicate webhook deliveries

Store the fx_rate value from triggered alerts for audit and decision-making

Set up monitoring for webhook delivery failures

Alert Management

Regularly review and deactivate alerts that are no longer relevant

Use descriptive alias values to identify alerts across your team

Monitor the updated_at field to track when alerts were last modified

Security

Validate all webhook signatures before processing

Use HTTPS endpoints for webhook delivery

Rotate your event_signature_key periodically

Common Use Cases

Rate Lock Timing

Risk Hedging

Opportunity Window

Scenario: Execute a large USD/COP payment when the rate falls below 4000

Configuration:

{
  "type": "fx_rate",
  "alias": "Execute Payment Window",
  "metadata": {
    "condition": "below",
    "currency_pair": "usd/cop",
    "min_rate": 4000
  },
  "valid_until": "2026-06-30T23:59:59Z"
}

Workflow:

Alert triggers when USD/COP < 4000

Webhook received with fx_rate: 3985.50

Automatically initiate rate lock via FX Rate Lock API

Execute cross-border payment at locked rate

Supported Currency Pairs

FX Rate Alerts currently support the following currency pairs:

Currency Pair	Description
`usd/cop`	US Dollar to Colombian Peso
`cop/usd`	Colombian Peso to US Dollar
`usd/mxn`	US Dollar to Mexican Peso
`mxn/cop`	Mexican Peso to Colombian Peso

Additional currency pairs may be supported in the future. Contact your Cobre representative for custom currency pair requests.

Error Handling

Common Error Scenarios

HTTP Status	Error	Resolution
`400 Bad Request`	Invalid condition type	Use `above`, `below`, or `within_range`
`400 Bad Request`	Missing required rate fields	Include `max_rate` for `above`, `min_rate` for `below`, both for `within_range`
`400 Bad Request`	Invalid currency pair	Use supported currency pairs only
`401 Unauthorized`	Invalid authentication	Check your API credentials and authorization header
`404 Not Found`	Alert ID does not exist	Verify the alert ID from your list of alerts
`422 Unprocessable Entity`	Invalid `valid_until` date	Ensure date is in the future and properly formatted

Rate Limits

Alert creation is subject to account limits.

Actions performed on FX Rate Alerts

➕ Create Alert

🔍 List All Alerts

📄 Get Alert by ID

🗑️ Deactivate Alert

Description: Create a new FX rate monitoring alert with custom conditions.

What to expect after the action:
A newly created Alert object with status active_status: true and a unique alert ID.

Webhook Notification:
Subscribers to alerts.fx_rate.created receive an immediate notification.

📘 Learn more: 🔗 Create Alert

How to Get Started

Subscribe to alert notifications

Subscribe to alerts.fx_rate.triggered.

Create your first alert

Send a POST request to /v1/alerts with your desired condition and currency pair.

Monitor webhook deliveries

Set up a webhook endpoint to receive notifications when alerts trigger.

Verify webhook signatures

Validate incoming webhooks using the event_signature header and your subscription's event_signature_key.

Take action on alerts

When an alert triggers, use the fx_rate value to decide whether to lock rates, execute payments, or adjust hedging strategies.

Manage alert lifecycle

List, retrieve, and deactivate alerts as market conditions change.

What to expect after using this API

Proactive FX risk management

React immediately to favorable or unfavorable market movements without manual monitoring.

Optimized cross-border payment timing

Execute transactions at the most advantageous rates by receiving instant notifications.

Reduced operational overhead

Automate currency monitoring instead of manually checking rates throughout the day.

Multi-currency portfolio coverage

Set up alerts across multiple currency pairs (USD/COP, USD/MXN, MXN/COP, etc.) simultaneously.

Audit trail and compliance

Maintain a complete history of alert configurations and trigger events for treasury reporting.

Integration with trading workflows

Use alert triggers as signals to initiate rate locks, quote requests, or payment executions through other Cobre APIs.

FX Alerts

Creating FX Rate Alerts#

FX Rate Alerts Lifecycle#

Alert Trigger Notification#

Alert Metadata#

Metadata Fields#

Alert Conditions Catalog#

Request Schema for Creating Alerts#

Field Descriptions#

Best Practices#

Alert Configuration#

Webhook Handling#

Alert Management#

Security#

Common Use Cases#

Supported Currency Pairs#

Error Handling#

Common Error Scenarios#

Rate Limits#

Actions performed on FX Rate Alerts#

How to Get Started#

What to expect after using this API#

Creating FX Rate Alerts

FX Rate Alerts Lifecycle

Alert Trigger Notification

Alert Metadata

Metadata Fields

Alert Conditions Catalog

Request Schema for Creating Alerts

Field Descriptions

Best Practices

Alert Configuration

Webhook Handling

Alert Management

Security

Common Use Cases

Supported Currency Pairs

Error Handling

Common Error Scenarios

Rate Limits

Actions performed on FX Rate Alerts

How to Get Started

What to expect after using this API