Verify first
Compute the HMAC over the timestamp, a dot and the raw body with the endpoint secret, compare in constant time with the value in X-Meteor-Signature, and reject timestamps older than five minutes. Do it before parsing: a re-serialised body will not match.
Acknowledge fast
You have 5 seconds to answer any 2xx. Do not do the work in the request: write the event to a queue or a table and return 200. A handler that updates three systems inline will time out on the day one of them is slow, and the retries will make it slower.
Deduplicate
Retries happen: 6 attempts over 24 hours. Every attempt carries the same event id. Store ids you have processed, with a unique index, and treat a duplicate as success. This is the whole of idempotent handling; it is one table.
Order by time
Delivery order is not guaranteed, and replays arrive days later by design. Keep the latest status by created_at and by precedence: a final state is never overwritten by sent. If you only store the last event received, a replayed sent will undo a delivered.
Monitor and replay
Alert on your own 5xx rate and on handler latency above two seconds. The panel shows per-endpoint success rate and lists undelivered events for 30 days; after an outage, fix the endpoint, then replay in bulk. Rotate the secret from the panel; both secrets are valid for 24 hours, so there is no downtime.
Something unclear or out of date? Write to [email protected]; corrections are folded back into the guide and the update date changes.