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.
| 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.
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
Slack
Telegram
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.
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.
signing_secret
returned on creation is used only when destination is generic.
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.
announcement_datetimecan be null. It is the publication time of the value, as on the announcements endpoint. When the publication time is not known yet, it isnullandpublication_time_statusisunknown. Accept a null value rather than rejecting the delivery.publication_time_statussays whatannouncement_datetimeis:confirmed(the publisher's own timestamp),unverified(a timestamp whose origin the row does not prove; withpublication_time_basisset toofficial_scheduleit is the publisher's scheduled release time), orunknown.official_planned_release_datetimeis 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
announcementevent is sent with the completed row. Itsdata.update_reasonispublication_time_updatedanddata.update_of_event_idnames the original event. It has its ownevent_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. |
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
statusbecomesdisabledand no further events are enqueued for it. Fix the destination, then reactivate it. - Secrets:
POST /v1/webhooks/subscriptions/{subscription_id}/rotate-secretreturns the newsigning_secretonce, in that response only. Deliveries signed after the rotation use the new secret. - Use
X-FXMD-Event-IDordata.event_idas 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.
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.