Provider event-stream webhooks

Subscribe via the developer console at /developer/webhooks. Every payload is HMAC-SHA256-signed and carries the canonical 14-tuple provenance block — your downstream system can verify the source origin without round-tripping back to Fonteum.

Phase 1 event types

• provider.exclusion_added
• provider.enrollment_status_changed

Phase 2 (queued): provider.deficiency_cited, provider.sff_status_changed, provider.ownership_changed.

Sample payload

{
  "event_id": "evt_2026_05_09_a1b2c3d4",
  "event_type": "provider.exclusion_added",
  "occurred_at": "2026-05-08T00:00:00Z",
  "delivered_at": "2026-05-09T18:32:14Z",
  "fonteum_version": "v2026.05.0",
  "subject": {
    "npi": "1245319599",
    "provider_name": null
  },
  "change": {
    "field": "leie_excluded",
    "old_value": null,
    "new_value": true,
    "exclusion_type": "1128(a)(1)",
    "exclusion_date": "2026-05-08"
  },
  "provenance": {
    "source": "OIG LEIE",
    "source_url": "https://oig.hhs.gov/exclusions/...",
    "dataset_id": "leie-2026-05-08",
    "snapshot_date": "2026-05-08",
    "methodology_version": "v2026.05.0",
    "last_checked": "2026-05-09T06:30:00Z",
    "confidence_score": 1,
    "data_availability": [
      "live"
    ],
    "pipeline_version": "abc1234",
    "doi": null,
    "license": "US-Government-Works",
    "coverage_period_start": "1977-10-25",
    "coverage_period_end": "ongoing",
    "slsa_provenance_url": null
  },
  "verify_url": "https://fonteum.com/verify/evt_2026_05_09_a1b2c3d4"
}

HMAC validation

Each POST carries an X-Fonteum-Signature header with format v1=hex_sig. Verify it against the raw request body using your subscriber secret (returned once at registration).

Node.js

// Node 18+ (built-in crypto)
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyFonteumSignature(
  rawBody: string,         // raw POST body string
  signatureHeader: string, // X-Fonteum-Signature header value, e.g. "v1=hex"
  secret: string,
): boolean {
  const expected = "v1=" + createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");
  if (expected.length !== signatureHeader.length) return false;
  return timingSafeEqual(
    Buffer.from(expected, "utf8"),
    Buffer.from(signatureHeader, "utf8"),
  );
}

Python

# Python 3.6+ (stdlib)
import hashlib, hmac

def verify_fonteum_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "v1=" + hmac.new(
        secret.encode("utf-8"),
        raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Go

// Go 1.21+
package fonteum

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)

func VerifyFonteumSignature(rawBody []byte, signatureHeader, secret string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(rawBody)
    expected := "v1=" + hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(signatureHeader))
}

Retry policy

• 5xx responses + timeouts (10s per request) → exponential backoff: 1m → 5m → 30m → 2h → 12h → DLQ.
• 4xx responses → marked failed, no retry. Inspect via the subscriber detail page.
• 2xx responses → success. last_active_at updated on the subscriber row.
• Every attempt logs to webhook_delivery_log with status, latency, and error class.
• After 6 retries (≈12h elapsed), the run moves to the Inngest dead-letter queue. Operator-side replay flow is documented separately.

Provenance contract

Every event payload includes the canonical 14-tuple provenance block. Original 8 fields: source, source_url, dataset_id, snapshot_date, methodology_version, last_checked, confidence_score, data_availability. Plus 6 fields added in §sprint3-14-tuple-extension: pipeline_version (git commit SHA), doi (Zenodo DOI for the methodology version), license (SPDX identifier), coverage_period_start + coverage_period_end (ISO-8601 dates), slsa_provenance_url (SLSA Build Level 3 artifact). The new fields are nullable; subscribers built against the original 8-field contract continue to receive valid payloads — they just ignore the 6 extra keys. The verify_url field links back to the per-event validation surface so your system can confirm the upstream snapshot fingerprint at any time. Full per-field reference at /docs/provenance-contract.

Source registry · Methodology · Freshness dashboard