Fundamentals Wire
Developer Docs

NewsML over HTTPS Push

Fundamentals Wire delivers each published press release as a full NewsML 1.2 document via HTTPS POST to an endpoint you control. Each publish event produces one immutable NewsML payload.

Integrate in one afternoon

Register an HTTPS endpoint, test delivery, then enable ongoing delivery.

Jump to examples
Copy/paste handler patterns and canonical field locations.
View examples →

Quickstart

  1. Provide an HTTPS endpoint (publicly reachable) and a technical contact.
  2. Verify delivery by returning a fast 2xx.
  3. Enable ongoing delivery once your handler is ready.
  4. Acknowledge fast (2xx) and process asynchronously (queue/job runner recommended).

Delivery contract

Method
POST
Content-Type
application/xml; charset=utf-8
Body
Full NewsML 1.2 XML (UTF-8)
Trigger
Publish event
Ack
Return 2xx to acknowledge receipt
Retries
Non-2xx responses or network failures may be retried. Your endpoint must be idempotent.

Authentication and integrity

Push deliveries can include a request signature header. If enabled for your integration, verify the signature against the raw request body bytes (before parsing XML). This prevents tampering and confirms the delivery source.

Recommended handler behavior

  • Read raw body bytes.
  • If signature is enabled: verify signature over raw bytes.
  • Enqueue for parsing/storage.
  • Return 204 (or any 2xx) immediately.

Stable identifiers and timestamps

NewsML provides two stable identifiers you should treat as primary keys, plus an authoritative publish timestamp. Use these to deduplicate, order, and reconcile deliveries across environments.

What to key on

Primary release key
<NewsItemId> (stable per release)
Global URN
<PublicIdentifier> (globally unique URN)
Authoritative publish time
<FirstCreated> (UTC)

Where to read what

The document is intentionally structured so an integrator can extract the same canonical values every time. Below is a compact map of “what you probably want” to “where it lives” in the NewsML payload.

Headline
//NewsComponent/NewsLines/HeadLine
Dateline
//NewsComponent/NewsLines/DateLine
Slugline (optional)
//NewsComponent/NewsLines/SlugLine
Canonical URL
NewsLine ClickThru URL and the XHTML footer link inside body content
Body content
A NewsComponent with <Role FormalName="Body"/> containing an XHTML ContentItem
Contacts (optional)
A NewsComponent with <Role FormalName="Contact"/> containing XHTML
Assets
Separate NewsComponent entries with roles such as Photo, Logo, Document, Video

Body content and XHTML

The full release body is delivered as an XHTML document inside a role component with FormalName="Body". Treat the XHTML as content (not code). If you render it, use a safe XHTML renderer or transform to your preferred internal format.

Canonical URL inside the payload

The canonical public URL is present as a “ClickThru URL” NewsLine and also appended to the XHTML body footer as a human-checkable source link. This makes it easy to reconcile your stored payload with the public release page.

Assets

Photos, logos, documents, and video are emitted as separate components with a role, rank, mime type, size, and an Href. Fetch the asset URL on demand. The payload includes enough metadata to preflight type and size before downloading.

Role
Photo / Logo / Document / Video
Ordering
<Rank> (document order)
Download URL
ContentItem Href="..."
Type / size
<MimeType> and <SizeInBytes>

Idempotency and retries

Your endpoint should be safe to receive duplicate deliveries. Retries can happen due to network failures, timeouts, or non-2xx responses. Deduplicate on NewsItemId (and optionally PublicIdentifier) before writing downstream state.

Practical guidance

  • Return 2xx once the payload is durably accepted (e.g., queued).
  • Make storage idempotent: ignore duplicates by primary key.
  • Log the publish timestamp (FirstCreated) for ordering and audit trails.

Examples

These examples are intentionally minimal. The goal is to show “what hits your endpoint” and where the canonical values live. You can accept the full payload as-is and store it verbatim alongside parsed fields.

Example HTTP request

POST /webhooks/fundamentals-wire/newsml HTTP/1.1
Host: example.com
Content-Type: application/xml; charset=utf-8
User-Agent: FundamentalsWire/1.0
X-FW-Delivery-Id: 74758d9a-99c8-4e5f-9f3f-2b7c2a0d5e11
X-FW-Signature: t=1700000000,v1=...

<?xml version="1.0" encoding="UTF-8"?>
<NewsML xmlns="http://iptc.org/std/NewsML/1.2/" Version="1.2">
  ...
</NewsML>

Respond with 204 (or any 2xx) once you’ve accepted the payload for async processing.

Fundamentals Wire NewsML profile: NewsML 1.2, press-release oriented, immutable per publish event.