Skip to main content

​
What counts as success

StockInsights sends each event as an HTTPS POST and waits for your response.
  • 2xx — the delivery is considered successful.
  • Anything else, a timeout, or a connection error — the delivery failed and is handled per the retry policy below.
Respond 2xx as soon as you have accepted the event. Acknowledge first, then do any slow work asynchronously — a slow handler risks hitting the timeout and being retried even though it succeeded.
Each request waits up to 10 seconds for a response before it is treated as a timeout and retried.

​
Retries

When a delivery fails, StockInsights retries with exponential backoff and full jitter — each retry is scheduled at a random point between zero and the backoff for that attempt, which spreads retries out and avoids thundering herds. A delivery is attempted up to 8 times in total — the first attempt plus 7 retries — using this backoff schedule: After the 8th attempt fails, the delivery is marked failed and the event is not sent again. In the worst case a delivery is retried for roughly two days before it is given up on.

​
Which failures are retried

Because a non-408/429 4xx is treated as permanent, make sure a failed signature check or an unexpected payload does not cause your endpoint to return, say, 400 or 404 for a request it should have accepted — that event is dropped, not retried. If your endpoint is in a state where it might recover (mid-deploy, secret not yet rolled out), return a 5xx so the delivery is retried. See rotating the secret.
Deliveries are also failed permanently, without retrying, when the destination URL cannot be delivered to safely: a non-HTTPS scheme, a hostname that does not resolve, or a hostname that resolves to a private or loopback address.

​
Ordering and duplicates

  • Delivery is at-least-once. Retries and network conditions mean the same event can arrive more than once. Make your handler idempotent by de-duplicating on the event id (the evt_... value).
  • Order is not guaranteed. Events can arrive out of order, especially when some were retried. Do not assume the order of receipt matches the order events occurred; use occurred_at if ordering matters to you.

​
Best practices

Acknowledge quickly

Return 2xx immediately and process asynchronously to avoid timeouts.

Be idempotent

De-duplicate on the event id so repeated deliveries are harmless.

Verify every request

Check the signature before acting on any payload.

Fail soft, not hard

Return 5xx when you might recover, so the delivery is retried rather than dropped.