Retries and duplicates

YOU(th) delivers every event at least once. A delivery your receiver does not take comes again, and one it took can come again too, after a network error. Build your receiver for both.

Answer fast

A delivery counts as taken when your receiver answers any 2xx within ten seconds.

1. Verify the signature.
2. If you have seen its event_id before, answer 200 and stop.
3. Store the event, answer 200, and do the work afterwards, outside the request.

Answering fast matters more than finishing the work: a receiver that reads the checkup before it answers can run past ten seconds, and then the same event comes again.

When YOU(th) tries again

Answer 4xx only when a delivery can never be taken, such as one whose signature fails.

YOU(th) makes up to eight attempts. The waits between them double from about one minute: about 1, 2, 4, 8, 16, 32 and 64 minutes, each varied by up to 20%, about two hours in all. After the eighth attempt, YOU(th) stops trying that event. Your YOU(th) contact can send it again on request, and the read API lists what you missed.

Take each event once

An event's event_id, also in the X-youth-event-id header, stays the same on every attempt. Keep the ids you have handled, for a few days at least, and skip one you have seen. Do not deduplicate on X-youth-delivery-id, which changes on every attempt.

Order

Deliveries can arrive in any order: a retry of an older event can come after a newer one. Read the current state from the API rather than relying on the order events came in.

Test your receiver

Ask your YOU(th) contact for a Ping.check delivery at any time. It is signed like every other and names no real member, so your receiver can answer it without reading anything.