Skip to content

Signed callbacks

Webhooks for macro release events

FXMacroData webhooks send HTTPS POST callbacks when matching macro announcements are processed. Use them when your server should react to release events without polling REST endpoints or holding open an SSE connection.

Create URL
https://api.fxmacrodata.com/v1/webhooks/subscriptions
Event
announcement
Delivery method
HTTPS POST with HMAC-SHA256 headers
Auth
Individual API key

Delivery choice

Use REST to fetch, SSE to listen, and webhooks to receive callbacks.

REST

Pull when your app decides.

Best for dashboards, backtests, and scheduled jobs that control their own request timing.

SSE

Keep a live client connection open.

Best for backend services and workers that can maintain a long-lived event stream.

Webhooks

Let FXMacroData call your server.

Best for alerts, cache invalidation, downstream jobs, and server-side release automation.

Subscription API

Create a webhook subscription.

A subscription stores the destination URL, event type, optional currency filters, optional indicator filters, an optional destination preset with its options, and a signing secret. The signing secret is returned only when a subscription is created or rotated.

curl -X POST "https://api.fxmacrodata.com/v1/webhooks/subscriptions" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/fxmacrodata/webhook", "events": ["announcement"], "currencies": ["usd", "eur"], "indicators": ["inflation", "policy_rate"], "description": "Macro release automation" }'
{ "id": "sub_9b4f5a", "url": "https://example.com/fxmacrodata/webhook", "status": "active", "events": ["announcement"], "currencies": ["usd", "eur"], "indicators": ["inflation", "policy_rate"], "destination": "generic", "destination_options": {}, "description": "Macro release automation", "failure_count": 0, "consecutive_failure_count": 0, "success_count": 0, "signing_secret": "whsec_..." }
Endpoint Method Use
/v1/webhooks/subscriptions POST Create a subscription and receive the first signing secret.
/v1/webhooks/subscriptions GET List your webhook subscriptions.
/v1/webhooks/subscriptions/{subscription_id} GET, PATCH, DELETE Read, update, disable, reactivate, or delete one subscription.
/v1/webhooks/subscriptions/{subscription_id}/rotate-secret POST Rotate the HMAC signing secret for one subscription.
/v1/webhooks/deliveries GET List recent delivery records, optionally filtered by subscription.

Destination rules

Webhook URLs must be public HTTPS endpoints.

Use a fully qualified public host over HTTPS. The URL must not include embedded credentials or a fragment. Return any 2xx response after your server stores or accepts the event.
Localhost, private network addresses, unresolved hosts, and non-HTTPS URLs are rejected. For endpoint testing, expose a temporary public HTTPS test endpoint and replace it before production use.

Destination presets

Send releases straight to Discord, Slack or Telegram.

Set destination on a subscription and FXMacroData posts each release as a readable message in the shape that platform expects, with no relay server in between. The default, generic, keeps the signed JSON event described below. Every chat message names the currency and indicator, the published value with its unit, the previous value when one exists, the official publication time in UTC, the FXMacroData capture latency when measured, and a link to the series page. One release produces one message.

Destination URL you provide Options Platform limits
generic Any public HTTPS endpoint None Signed JSON event, see payload and signatures.
discord https://discord.com/api/webhooks/{id}/{token} username, prefix Message content up to 2,000 characters plus one embed. Discord rate limits per webhook; a deleted webhook answers 404.
slack https://hooks.slack.com/services/T.../B.../... username, prefix About one message per second per channel. Text and blocks are kept under 3,000 characters.
telegram https://api.telegram.org/bot{token} chat_id (required), parse_mode, prefix Text up to 4,096 characters. One message per second per chat and 20 per minute per group.
airtable https://hooks.airtable.com/workflows/v1/genericWebhook/{app}/{wfl}/{wtr} None One flat JSON record per release for an Airtable automation. See Airtable.

prefix is free text of up to 100 characters placed in front of every message, for example @here on Discord, <!channel> on Slack or a desk name on Telegram. A URL that does not belong to the chosen destination, a Telegram subscription without chat_id, or an Airtable subscription with destination_options or a query string on its URL, is refused with HTTP 422 and nothing is stored.

Discord

Get a webhook URL.

In your server open Server Settings, then Integrations, then Webhooks. Create a webhook, pick the channel and copy its URL.

Slack

Get an incoming webhook URL.

Create a Slack app for your workspace, enable Incoming Webhooks, add a webhook to the channel you want and copy the URL that starts with hooks.slack.com/services/.

Telegram

Get a bot token and chat ID.

Create a bot with @BotFather and copy its token. Add the bot to your group or channel as an administrator. The chat ID is the numeric ID of that group or channel, or the public @channel username.

Discord

curl -X POST "https://api.fxmacrodata.com/v1/webhooks/subscriptions" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://discord.com/api/webhooks/123456789012345678/YOUR_WEBHOOK_TOKEN", "destination": "discord", "destination_options": {"username": "FXMacroData", "prefix": "@here"}, "currencies": ["usd", "eur"], "indicators": ["inflation", "policy_rate"] }'

Slack

curl -X POST "https://api.fxmacrodata.com/v1/webhooks/subscriptions" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://hooks.slack.com/services/T00000000/B00000000/YOUR_WEBHOOK_SECRET", "destination": "slack", "destination_options": {"prefix": "<!channel>"}, "currencies": ["usd"] }'

Telegram

curl -X POST "https://api.fxmacrodata.com/v1/webhooks/subscriptions" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://api.telegram.org/botYOUR_BOT_TOKEN", "destination": "telegram", "destination_options": {"chat_id": "-1001234567890", "parse_mode": "HTML"}, "currencies": ["gbp", "jpy"] }'

A Telegram message is sent to sendMessage on the bot URL you stored. parse_mode is HTML by default; use plain for unformatted text. Numeric chat IDs and @channel usernames are both accepted.

Airtable

The airtable destination posts one flat JSON record per release to an Airtable automation that uses the When webhook received trigger. Every top-level field is available as a token in the automation: value and previous map to Number fields, published_at is an ISO 8601 UTC time for date fields, and record_key identifies the release so an automation can find and update an existing row. Use the automation's webhook URL exactly as Airtable shows it, without a query string. Table setup, field mapping and other Airtable workflows are in the Airtable guide.

curl -X POST "https://api.fxmacrodata.com/v1/webhooks/subscriptions" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://hooks.airtable.com/workflows/v1/genericWebhook/appXXXX/wflXXXX/wtrXXXX", "destination": "airtable", "currencies": ["usd", "eur"] }'

Record fields: event_id, event, record_key, currency, indicator, name, period, value, value_text, previous, previous_text, unit, published_at, latency_ms, headline, source_url and series_url.

{ "event_id": "usd_inflation_1789129800", "event": "announcement", "record_key": "usd:inflation:2026-08-31", "currency": "USD", "indicator": "inflation", "name": "Inflation (CPI)", "period": "2026-08-31", "value": 3.4, "value_text": "3.4 %YoY", "previous": 3.4, "previous_text": "3.4 %YoY", "unit": "%YoY", "published_at": "2026-09-11T12:30:00Z", "latency_ms": null, "headline": "USD Inflation (CPI): 3.4 %YoY", "source_url": "https://www.bls.gov/news.release/archives/cpi_09112026.htm", "series_url": "https://fxmacrodata.com/api-data-docs/usd/inflation" }
Discord, Slack and Telegram deliveries are not signed. Those platforms ignore custom headers, and the webhook URL or bot token is itself the credential, so keep it private. Airtable deliveries are unsigned for the same reason. The signing_secret returned on creation is used only when destination is generic.
Rate limiting (HTTP 429) is retried on the normal schedule and the platform's Retry-After value is recorded on the delivery. A destination that answers HTTP 404, such as a deleted Discord webhook or a revoked bot token, disables the subscription at once with disabled_reason set to destination_not_found. Update the URL to reactivate it.

Delivery payload

Each delivery includes the event, delivery ID, and announcement data.

Webhook payloads use the same event_id, currency, indicator, records_written, and latest_announcement fields used by release events. Fetch the matching announcements endpoint when your application needs the complete time series.

{ "id": "usd_inflation_1772109000", "event": "announcement", "created": 1772109002, "subscription_id": "sub_9b4f5a", "delivery_id": "sub_9b4f5a_usd_inflation_1772109000", "data": { "event_id": "usd_inflation_1772109000", "currency": "usd", "indicator": "inflation", "records_written": 1, "latest_announcement": { "date": "2026-06-12", "val": 3.0, "announcement_datetime": 1781267400, "publication_time_status": "confirmed", "publication_time_precision": "minute", "official_planned_release_datetime": 1781267400 } } }
  • announcement_datetime can be null. It is the publication time of the value, as on the announcements endpoint. When the publication time is not known yet, it is null and publication_time_status is unknown. Accept a null value rather than rejecting the delivery.
  • publication_time_status says what announcement_datetime is: confirmed (the publisher's own timestamp), unverified (a timestamp whose origin the row does not prove; with publication_time_basis set to official_schedule it is the publisher's scheduled release time), or unknown.
  • official_planned_release_datetime is the release time on the publisher's official calendar, when one exists. It is a scheduled time, not a publication time.
  • Publication-time updates. When a delivered value later gains a publication time, a second announcement event is sent with the completed row. Its data.update_reason is publication_time_updated and data.update_of_event_id names the original event. It has its own event_id.

Signature verification

Verify every delivery before processing it.

FXMacroData signs the timestamp, event ID, and request body with the subscription signing secret. Store the secret securely, compare signatures with a constant-time comparison, and reject stale timestamps.

Header Meaning
X-FXMD-Event Webhook event name. Currently announcement.
X-FXMD-Event-ID Stable event ID for idempotency.
X-FXMD-Delivery-ID Unique delivery record ID.
X-FXMD-Timestamp Unix timestamp used in the signed message.
X-FXMD-Signature v1= followed by the HMAC-SHA256 hex digest.
import hashlib import hmac import time def verify_fxmd_webhook(headers, raw_body, signing_secret): timestamp = headers["X-FXMD-Timestamp"] event_id = headers["X-FXMD-Event-ID"] supplied = headers["X-FXMD-Signature"].removeprefix("v1=") if abs(time.time() - int(timestamp)) > 300: raise ValueError("stale webhook timestamp") signed = f"{timestamp}.{event_id}.{raw_body.decode('utf-8')}".encode("utf-8") expected = hmac.new( signing_secret.encode("utf-8"), signed, hashlib.sha256, ).hexdigest() if not hmac.compare_digest(supplied, expected): raise ValueError("invalid webhook signature")

Retries and idempotency

Return 2xx only after your system accepts the event.

FXMacroData treats any 2xx response as delivered. Each attempt waits up to 10 seconds for your response. A timeout, a connection error, HTTP 408, 409, 425 or 429, or any 5xx is retried; every other 4xx is a final failure for that delivery and is not retried.

  • Schedule: up to 8 attempts per delivery. The first retry follows about one second after the failure and the wait doubles, up to a cap of 60 seconds between attempts, so a delivery that never succeeds is abandoned within a few minutes rather than hours.
  • Attempt count: attempt_count, the last status code and the last error are recorded on each delivery and visible in the delivery logs.
  • Auto-disable: after 10 consecutive failed deliveries the subscription's status becomes disabled and no further events are enqueued for it. Fix the destination, then reactivate it.
  • Secrets: POST /v1/webhooks/subscriptions/{subscription_id}/rotate-secret returns the new signing_secret once, in that response only. Deliveries signed after the rotation use the new secret.
  • Use X-FXMD-Event-ID or data.event_id as your idempotency key.
  • Store processed event IDs before triggering downstream side effects.
  • Return 2xx for duplicate event IDs that were already processed successfully.
  • Use PATCH /v1/webhooks/subscriptions/{subscription_id} with {"status":"active"} after fixing a disabled destination.

Delivery logs

Inspect recent webhook delivery records.

Delivery logs show status, attempt count, last status code, last error, and timestamps. Use them for support triage, retry visibility, and destination debugging.

curl -H "X-API-Key: YOUR_API_KEY" "https://api.fxmacrodata.com/v1/webhooks/deliveries?subscription_id=sub_9b4f5a&limit=25"
{ "data": [ { "id": "sub_9b4f5a_usd_inflation_1772109000", "subscription_id": "sub_9b4f5a", "event_id": "usd_inflation_1772109000", "event": "announcement", "status": "succeeded", "attempt_count": 1, "last_status_code": 204, "last_error": null, "delivered_at": "2026-06-12T12:30:04Z" } ], "count": 1 }

Troubleshooting

Common setup checks.

Subscription creation returns 400 or 422.

A 400 means the URL is not a public HTTPS endpoint: check the scheme, the host and that it has no embedded credentials or fragment. A 422 means the URL, destination and destination_options disagree, for example a Slack URL on a Discord destination or a Telegram subscription without chat_id.

No deliveries arrive.

Confirm the subscription is active and that its currency and indicator filters match the release event.

Signature verification fails.

Use the exact raw request body, the received timestamp, the received event ID, and the current signing secret.

Deliveries keep retrying.

Return a 2xx response after accepting the event. Inspect delivery logs for the last status code and error text.

AI Answer-Ready

Key Facts

Page
Webhooks
Section
Documentation
Canonical URL
https://fxmacrodata.com/documentation/webhooks
Source
FXMacroData editorial and official publisher references
Last Updated
See page metadata

Provenance And Trust

Cite the canonical URL and source field above. Where available, this page maps to official publisher releases and timestamped updates.

Quick Q&A

What is this page about? This page explains Webhooks with directly usable context for trading, research, and API workflows.

What source should be cited? Use the canonical URL and the listed source field; cite official publisher references when available.

How fresh is this content? The last updated value above reflects the page metadata or latest available data timestamp.

Can this be used in AI assistants? Yes. This section is intentionally structured for retrieval and citation in chat assistants.

Prompt Packs

Use these in ChatGPT, Claude, Gemini, Mistral, Perplexity, or Grok for consistent source-aware outputs.