Macro trading teams spend a lot of energy around timing. Before a Federal Reserve decision, a US CPI print, or a payrolls release, the question is not only "what did the number say?" It is also "how quickly did our systems know, what exactly triggered the workflow, and can we prove the downstream job reacted to the right event?"
FXMacroData webhooks are built for that gap between scheduled macro awareness and operational response. The release calendar tells you what is coming. REST gives you the full historical and current record. Server-Sent Events are useful when a connected client can listen continuously. Webhooks give your backend a clean callback surface: when a release lands, FXMacroData calls your server with a signed event.
Teams running alerting, cache refreshes, release-review queues, data warehouses, or customer dashboards that should respond to actual macro events.
Use SSE streams when a browser dashboard or worker can keep a live connection open and handle reconnects directly.
The webhook is the trigger. The complete time series and full response contract remain in the matching REST endpoint.
What's New
FXMacroData now supports customer-managed webhook subscriptions for macro announcement events. A subscription lets a Professional account register a public HTTPS destination, choose the announcement event, and optionally narrow delivery to the currencies and indicators a system actually watches.
The important change is not just "another notification method." It is a different operating model. A polling job asks the same question on a schedule: has anything changed yet? A webhook workflow waits for the release event itself, then does the work only once the event exists.
Subscribe to the currencies and indicators your workflow needs, such as USD inflation or EUR policy-rate events.
Each delivery includes signature headers so your receiver can verify the source before triggering side effects.
Delivery records expose status, attempt count, last status code, and recent error context for support and operations.
The webhook payload includes the stable event ID, event type, subscription ID, delivery ID, currency, indicator, records written, and latest announcement snapshot. That is enough to decide what to refresh, alert, or enqueue. If the workflow needs the full record, it follows the event back to the corresponding announcement endpoint.
Why It Matters for Traders
FX teams often know the calendar in advance but still rely on crude mechanics after the release. A scheduler wakes up every minute, calls the endpoint, checks whether the latest value changed, and then tries to decide whether to alert the desk. That works, but it mixes three jobs that should be separate: knowing the schedule, detecting the publication, and running the action.
Webhooks separate those jobs. The release calendar remains the planning surface. The webhook is the publication signal. REST is the source of truth for data retrieval. That separation is valuable because it gives each part of the workflow a clear responsibility.
Systems stop asking for unchanged data just to find out whether a release landed.
A stable event ID and delivery ID make it easier to trace what triggered a downstream action.
Alerts, dashboards, and model jobs can update because a macro event arrived, not because a timer guessed correctly.
For a discretionary trader, this can mean an alert that arrives with a clear event reference and a link to the refreshed series. For a quant developer, it can mean cache invalidation that runs once per event instead of constantly scanning for state changes. For a platform team, it can mean customer dashboards that refresh on publication without each customer polling independently.
Where Webhooks Fit
The three FXMacroData delivery patterns now cover different integration shapes. The right choice depends less on the data itself and more on where the decision loop lives.
| Pattern | Best fit | Tradeoff |
|---|---|---|
| REST | Backtests, scheduled reports, research notebooks, and dashboards that fetch on demand. | Your system decides when to ask, so release detection can become a polling problem. |
| SSE | Live clients that can keep an EventSource connection open and handle reconnects. | A connection has to stay alive; this is natural for some clients and awkward for others. |
| Webhooks | Server-side automation, cache invalidation, alerting, data pipelines, and workflow queues. | Your receiver must expose a public HTTPS endpoint and verify signatures correctly. |
Practical Example: USD Inflation Alerting
Imagine a desk that watches USD inflation because it feeds directly into rate-path expectations and short-term dollar risk. The team already reviews the calendar before the release. What they want after publication is a clean trigger: refresh the inflation record, compare the print against the desk threshold, and send the result into their alert channel.
The subscription can be narrowed to one currency and one indicator:
curl -X POST "https://fxmacrodata.com/api/v1/webhooks/subscriptions?api_key=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/fxmacrodata/releases",
"events": ["announcement"],
"currencies": ["usd"],
"indicators": ["inflation"],
"description": "USD inflation release alert"
}'
A representative create response includes the subscription configuration and the signing secret:
{
"id": "sub_9b4f5a",
"url": "https://example.com/fxmacrodata/releases",
"status": "active",
"events": ["announcement"],
"currencies": ["usd"],
"indicators": ["inflation"],
"failure_count": 0,
"consecutive_failure_count": 0,
"success_count": 0,
"signing_secret": "whsec_..."
}
When the event arrives, the receiving service verifies the signature, stores usd_inflation_1772109000 as the idempotency key, and fetches the refreshed series:
curl "https://fxmacrodata.com/api/v1/announcements/usd/inflation?api_key=YOUR_API_KEY"
The interpretation is simple: if the latest value breaches the team's inflation surprise threshold, the alert gets promoted; if not, the event is still recorded and the dashboard cache is refreshed. The webhook does not replace analysis. It removes the uncertainty around when the analysis workflow should run.
Practical Example: Policy-Rate Monitoring
A second common use case is a rate-monitoring workflow. Suppose a platform watches policy-rate events across USD and EUR so customer dashboards refresh after central-bank decisions. The subscription can cover both currencies while staying focused on policy-rate releases:
curl -X POST "https://fxmacrodata.com/api/v1/webhooks/subscriptions?api_key=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/fxmacrodata/policy-rate-webhook",
"events": ["announcement"],
"currencies": ["usd", "eur"],
"indicators": ["policy_rate"],
"description": "Policy-rate dashboard refresh"
}'
A delivery for a policy-rate event carries the event identity and latest release snapshot:
{
"id": "eur_policy_rate_1773932400",
"event": "announcement",
"created": 1773932402,
"subscription_id": "sub_82ce31",
"delivery_id": "sub_82ce31_eur_policy_rate_1773932400",
"data": {
"event_id": "eur_policy_rate_1773932400",
"currency": "eur",
"indicator": "policy_rate",
"records_written": 1,
"latest_announcement": {
"date": "2026-03-19",
"val": 3.5,
"announcement_datetime": "2026-03-19T13:00:00Z"
}
}
}
That event can invalidate a dashboard cache, queue a rate-summary job, or notify a customer-facing application that the EUR policy-rate record should be reloaded. If the receiver sees the same event ID twice because a retry occurred, it can safely acknowledge the duplicate after confirming the first attempt already succeeded.
Operating Model: Verify, Store, Then Act
Webhook receivers should be boring in the best possible way. They should verify the signature, store the event ID, accept the delivery quickly, and push heavier work into their own queue or job system. That keeps the callback endpoint reliable even when a release triggers more expensive analysis later.
Check the HMAC signature headers and reject stale or unsigned requests before any downstream action.
Use the event ID as the durable key so retries do not create duplicate alerts, refreshes, or model runs.
Call REST for the full announcement record after accepting the webhook trigger.
Use delivery logs to inspect status, attempt count, last status code, and recent error context.
The design is intentionally conservative. Webhooks are not a replacement for the data contract, and they are not a place to do long-running analysis inline. They are the release signal that lets the rest of the workflow start at the right time.
Common Questions
Do webhooks replace REST?
No. Webhooks tell your server that a matching event happened. REST remains the canonical source for the complete macro record and historical series.
Do webhooks replace SSE?
No. They solve a different integration problem. Use SSE for clients that should keep a live stream open. Use webhooks when a backend service should receive signed callbacks.
What should the receiver return?
Return a 2xx response after the event is accepted or confirmed as an already-processed duplicate. If the receiver times out or returns a retryable error, delivery may be attempted again.
Get Started
Start with the webhooks documentation to create a subscription, review URL rules, verify signature headers, rotate secrets, and inspect delivery logs. If you are still deciding between delivery models, compare the webhook flow with SSE streams and the announcement endpoint guide.
A practical first implementation is narrow: subscribe to one high-impact indicator such as USD inflation, store the event ID on delivery, fetch the refreshed REST record, and send one desk alert or dashboard refresh. Once that path is reliable, expand the same pattern to policy rates, GDP, labor data, and the rest of the release workflows that matter to your desk.
