Best practices and troubleshooting

Responding correctly

Reply with a 2xx code as fast as possible, set the delivery’s content aside, and process it asynchronously afterwards. Three reasons dictate this order, the first being the most important.

1. A duplicate is guaranteed if you are too slow. Ciklik waits 30 seconds for your response. If your processing exceeds this delay before responding, Ciklik considers the delivery lost and replays it up to four times, even though your server did receive it and may already have processed it four times. Responding first, then processing, is the only defence against this duplicate.
2. Ciklik does not inspect the code you return. A 500 on your side triggers no new delivery: the loss is immediate and final.
3. Never respond with a redirect. A redirect wipes out the delivery’s content (see below) and leaves a misleading trace.

What is retried, what is not

Situation	Behaviour
Unreachable receiving URL, broken DNS, connection refused, connection timeout, invalid certificate	5 attempts in total: 30 seconds between the first three, then the last two in immediate succession
4xx or 5xx response	No further attempt: the delivery is considered delivered
Too many redirects followed	Immediate attempts, then abandonment

A 500 on your side is a definitive loss

Ciklik never re-reads the response code. An application error on your side is not replayed: process the content defensively, in a queue you control, once the 2xx has been sent.

Absorbing duplicates and out-of-order deliveries

• Process by object identifier (id or uuid), never by arrival order. Order is not guaranteed: deliveries leave with different delays and several deliveries may be processed in parallel, so an updated_* delivery can arrive before the created_* of the same object.
• Compare the received state with your local state before acting, rather than blindly applying a difference. The delivery’s content reflects the object’s state at the moment Ciklik sent it, not at the moment of the event: only changed reflects the exact instant of the event.
• Make your processing replayable. The same delivery received twice must produce the same result as when received once: this is the only real protection against duplicates, which are frequent (cascades, successive saves, resends on slow responses).
• Ignore a delivery whose object timestamp is older than the one already recorded on your side. This is what protects you when two deliveries arrive out of order.

Securing your receiving URL

There is neither a signature nor a shared secret in a Ciklik delivery: no authentication header, nothing to verify in the body. Your receiving URL is therefore the only secret in the setup.

• Use HTTPS. Over plain HTTP, your customers’ data travels in clear text.
• Choose a long, unguessable path, never /webhook or /hook.
• Never publish this URL, do not put it in a public repository or in a shared configuration file.
• Ciklik does not publish a fixed IP address for its deliveries: do not filter by IP address, it is the unguessable path that protects your URL.
• Your certificate must be valid and issued by a recognised authority.

An invalid certificate leaves no trace

A self-signed or expired certificate makes the delivery fail without any line being written in the log the Ciklik team can share with you: see below.

Two additional rules, independent of the protocol:

• Verify any critical information through a call to the Ciklik API before acting on money or on shipping a parcel. The delivery’s content is not an order, it is a notification.
• Use and store only the documented fields. The content includes personal data of your customers and internal technical fields that may change without notice. Treat this content as personal data within the meaning of the GDPR.

Diagnosing

1. Replay a test delivery to your receiving URL, from the outside, with a sample content. First save the example from the Events: subscriptions page into a sample-created_subscription.json file.

   curl -X POST https://your-receiving-url/path \
     -H "Content-Type: application/json" \
     -d @sample-created_subscription.json

2. Check that there is no redirect.

   curl -sS -o /dev/null -w "%{http_code} %{redirect_url}\n" https://your-receiving-url/path

   A 301, 302 or 303 code, or a value after the code, indicates a redirect: Ciklik’s content is lost there.

3. Check the certificate, without ever using the --insecure option.

   curl -sSI https://your-receiving-url/path

   If this command fails, your certificate is not valid.

4. Check that the enabled event key matches the action you just performed: a test on updated_subscription produces nothing if you just created an order.

5. Wait 60 seconds after any configuration change: a new receiving URL takes up to one minute to be taken into account.

6. Ask the Ciklik team for the trace of the delivery matching your test.

Reading the trace kept by the team

This is the decisive step: for every delivery that actually left, the Ciklik team keeps the URL called, the content sent, the code and body of the response received, and the time. Its state reads as follows:

• No trace for the period: the connection never succeeded. DNS, connection refused, connection timeout or invalid certificate are the possible causes. Nothing left, and in this specific case no line is ever written: the absence of a trace is not a logging defect, it is the information itself.
• Trace with a 200 code and an HTML body: your URL most likely redirected. The content was lost on the way, and the recorded 200 is that of the landing page, not proof of processing.
• Trace with a 4xx or 5xx code: the delivery did reach you, your server refused it, and it will never be replayed.
• The recorded time is that of the response, not that of the trigger. A gap of several seconds from the original action is normal.

These traces are kept for 20 days.

FAQ

Can I declare several URLs for the same event?

No. One URL per event key: a new declaration always replaces the previous one, without warning.

How do I know which event it is on receipt?

The event name is not in the delivery’s content. You know it from the URL you registered for that event key.

Why do I receive the same event several times?

Three common causes: cascades that save the same object several times within a single flow, legitimate successive saves, or a response that is too slow on your side and triggers a resend (see “Responding correctly”).

Why do I receive nothing when a shipment actually leaves?

The transition to the shipped status triggers an updated_shippingbox only when it is made through the vendors API or through the Ciklik team’s tracking-number import. It is never notified when it comes from the Wonderweb or Effitrace logistics connectors: on those channels, follow the shipment updates that precede the physical dispatch instead, or query the API.

Can I ask for a missed delivery to be replayed?

No, there is no on-demand resend. Use the Ciklik API to retrieve the current state of the object concerned.

Should I verify a signature on each delivery?

There is none: no Ciklik delivery is signed. It is your unguessable receiving URL that protects the setup.

How long do you keep the trace of a delivery?

20 days. Beyond that, the trace no longer exists: request it as soon as you start diagnosing an issue.