Key concepts
Sources, columns, delivery targets and track ids — the vocabulary shared by both ingestion flows.
Both flows move a file into the same destination and speak the same vocabulary. This page defines it once.
Source
A source is the resource your reconciliations read from. JaaS creates it for you — in the platform and in its own registry — and returns its id. That id is what ties every later file to the right place.
A source belongs to one workspace, and the workspace belongs to an account. Both travel in the request headers, and the workspace is also what your credential is validated against.
Columns and mapping
A source declares its columns up front. Each column has:
| Field | What it does |
|---|---|
name | The column name in the resulting CSV. |
position | Column order in the CSV, starting at 1. |
mapping | Where to read the value from in your JSON. Supports dot notation for nested objects — payment.amount. |
data_type | One of string, numeric, integer, boolean, date, datetime, time. |
format_notation | The format the value comes in — mostly used for dates. Empty string when it doesn't apply. |
Columns matter in the file ingestion flow, where JaaS builds the CSV from the records you post. In the webhook flow the file is delivered as you published it, so the source is created with a placeholder column and the schema that counts is the one inside your file.
A mapping that finds nothing produces an empty cell, not an error. If a whole column comes out blank, the mapping path is the first thing to check.
Delivery target
Depending on how your workspace is set up, a source is fed either directly to reconciliation or through storage. The create response tells you which one you got, as resource_type:
resource_type | What it means for you |
|---|---|
SOURCE | The file is delivered to reconciliation, and reconciliation is notified when it lands. |
REPOSITORY | The file is delivered to your storage zone, and reconciliation picks it up from there. |
This is decided per workspace when Simetrik onboards you — you don't choose it per request, and it doesn't change how you send files. It only changes which of the two paths the file takes once it's inside.
Records, files and their lifecycle
In file ingestion you post records and Simetrik groups them into a file; in the webhook flow each notification produces one file directly. Either way the file — not the record — is the unit that gets tracked from capture to delivery. The exact states differ per flow — see file lifecycle for file ingestion and for the webhook flow — but the shape is the same: captured, downloaded, processed, delivered, or failed at one of those steps.
A failure on one file doesn't stop the others in the same batch.
Webhook source and webhook file
Only in the webhook flow:
- A webhook source is the registration: the URL field to read, the credentials to download with, and the response your systems expect back. It's created once and returns a
webhook_id. - A webhook file is one individual file, created every time you send a notification to that webhook.
Track id
A track id is your end-to-end correlation identifier, and it belongs to the webhook flow. You send it as a header on the inbound notification; Simetrik stores it with the file and echoes it back on every status notification, both as a payload field and as an HTTP header.
| Default | Configurable per source | |
|---|---|---|
| Inbound header | X-Correlation-Id | inbound_track_id_header_name |
| Outbound payload field | correlation_id | outbound_track_id_field_key |
| Outbound header | X-Correlation-Id | Derived from the field name — trace_id becomes X-Trace-Id |
Rules worth knowing before you pick a value:
- Maximum 128 characters. Longer values are rejected with
400. - No control characters. Also rejected with
400. - The outbound field name can't be
event_type,timestampordata— those are already taken by the payload. - Sending no track id is valid. The field and the header are simply omitted.
File ingestion has no track id. Records are batched before anything is processed, so a notification describes a file rather than one of your calls — correlate on the source and the time window. What you do get per call is the sk-int-id in the feed response, which is a support reference, not a value that comes back in notifications.
Limits and timeouts
| Value | |
|---|---|
| Track id length | 128 characters |
| File download from your URL (webhook flow) | 300 seconds |
| Status notification delivery | 10 seconds per attempt, up to 3 attempts |