Status notifications

JaaS has no status endpoint to poll. Instead, you register a notification_config on the source and Simetrik posts to your endpoint every time a file changes state. It works identically for file ingestion and the webhook flow.

You register it in the same call that creates the source — either POST /api/v2/sources or POST /api/v2/webhooks.

Configuration

{
  "notification_config": {
    "target_url": "https://hooks.example.com/simetrik/files",
    "events": [
      "download_status.completed",
      "download_status.download_failed",
      "download_status.validation_failed",
      "download_status.processing_failed"
    ],
    "auth_config": {"type": "bearer", "token": "…"},
    "signing_secret": "…",
    "inbound_track_id_header_name": "X-Trace-Id",
    "outbound_track_id_field_key": "trace_id"
  }
}

Events

Which internal state maps to which event is listed per flow, in file ingestion and in the webhook flow.

The payload

{
  "event_type": "download_status.completed",
  "timestamp": "2026-09-14T18:04:21.512890+00:00",
  "trace_id": "settlement-2026-09-14-run-3",
  "data": {
    "webhook_file_id": "b8f1c2e4-…",
    "webhook_source_id": "61171_wh_9d200105",
    "source_id": "61171",
    "filename": "settlements-2026-09-14.csv",
    "file_url": "https://files.example.com/settlements/2026-09-14.csv",
    "status": "completed",
    "file_size_bytes": 184320,
    "downloaded_at": "2026-09-14T18:04:19.004112",
    "file_resource_path": "…/61171/8c3e….csv"
  }
}

Headers

Verifying the signature

The signature is an HMAC-SHA256 over the payload serialized with its keys sorted, using your signing_secret. Since the body arrives in its natural order, re-serialize it before computing the digest:

import hashlib
import hmac
import json


def is_authentic(raw_body: bytes, signature_header: str, signing_secret: str) -> bool:
    payload = json.loads(raw_body)
    canonical = json.dumps(payload, sort_keys=True, ensure_ascii=True).encode("utf-8")
    expected = hmac.new(signing_secret.encode("utf-8"), canonical, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature_header)

Outside Python, three details have to match exactly, or the digest won't:

• Keys sorted at every level.
• , between entries and : after each key — the separators Python writes by default.
• Non-ASCII escaped as \uXXXX. This is the one that bites: a filename with an accent is signed in its escaped form, so a serializer that emits raw UTF-8 produces a different digest. ensure_ascii=True is Python's default and is passed explicitly above to make the requirement visible.

Authenticating against your endpoint

Delivery and retries

• 10 seconds per attempt, 3 attempts maximum.
• Retried on network errors and on 5xx. Backoff is exponential with jitter.
• Not retried on 4xx — that's read as a permanent rejection.
• X-Webhook-Delivery-Id stays the same across retries, so deduplicate on it.

Notifications are fire-and-forget: a delivery that fails every attempt is logged on the Simetrik side and dropped. It never affects the file, which is already on its way. So treat these notifications as a fast path, not as the ledger — if one never arrives, the file may well have been delivered anyway.

Answer with any 2xx as soon as you've accepted the payload, and do your own work afterwards. Anything slower than 10 seconds reads as a failed attempt and gets retried.