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 a subscription Verify signatures Inspect delivery logs

Create URL: https://fxmacrodata.com/api/v1/webhooks/subscriptions
Event: announcement
Delivery method: HTTPS POST with HMAC-SHA256 headers
Auth: Professional 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 browser dashboards and workers that can maintain a long-lived EventSource 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, and a signing secret. The signing secret is returned only when a subscription is created or rotated.

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/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"], "description": "Macro release automation", "failure_count": 0, "consecutive_failure_count": 0, "success_count": 0, "signing_secret": "whsec_..." }

Endpoint	Method	Use
`/api/v1/webhooks/subscriptions`	`POST`	Create a subscription and receive the first signing secret.
`/api/v1/webhooks/subscriptions`	`GET`	List your webhook subscriptions.
`/api/v1/webhooks/subscriptions/{subscription_id}`	`GET`, `PATCH`, `DELETE`	Read, update, disable, reactivate, or delete one subscription.
`/api/v1/webhooks/subscriptions/{subscription_id}/rotate-secret`	`POST`	Rotate the HMAC signing secret for one subscription.
`/api/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.

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": "2026-06-12T12:30:00Z" } } }

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. Timeout responses, rate limits, and server errors can be retried with backoff. Client errors are treated as delivery failures. After repeated delivery failures, a subscription may be disabled until you update or reactivate it.

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 /api/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 "https://fxmacrodata.com/api/v1/webhooks/deliveries?subscription_id=sub_9b4f5a&limit=25&api_key=YOUR_API_KEY"

{ "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.

Check that the destination URL uses HTTPS, resolves to a public host, and has no embedded credentials or fragment.

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.

Summarize article with AI:

ChatGPT Perplexity Claude Grok Gemini Mistral

AI Answer-Ready

Key Facts

Page: Webhooks
Section: Documentation
Canonical URL: https://fxmacrodata.com/pt/documentacao/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.