4. Registering events

4.1 The call

POST /events with your channel key. Depending on the channel's modality:

• Content (JSON): client_ref + payload (up to 256 KB).
• Content (file): multipart with client_ref + file (up to 10 MB).
• Hash-only: client_ref + hash + hash_alg (sha-256 or sha-512). You compute the digest of the data you hold; the data itself is never sent.

occurred_at is optional and is part of your declaration: it states when you claim the fact happened. What Safe Creative attests with the timestamp is received_at — when it was received. Reports always keep the two apart.

4.2 Idempotency: retry without fear

client_ref is your unique event id (per channel). If you retry the same call — timeout, network drop — the event is not duplicated: you get 200 with the original event. If you reuse a client_ref with different content, you get 409: nothing is ever overwritten.

Rule of thumb: generate the client_ref before calling (your transaction id, a persisted UUID) and retry with exponential backoff on 5xx or timeouts. That makes your integration outage-proof. And if your process cannot afford to drop declarations during a longer outage, add a local outbound queue (a persistent buffer you resend from): your events will come in once the service is back, each with its actual reception time.

4.3 Sequence and ordering

The sequence number is assigned by the service at reception: strictly increasing, gapless, per channel. The probative order is the order of reception, not occurred_at. If the order of your events matters, send them in order or serialize your calls.