Unexpected Order of Loyalty Event Payloads in loyalty.account.updated Webhook

Questions
,
1

Hi Square Team,

I’ve observed an issue with the loyalty.account.updated webhook payloads that seems inconsistent with expectations.

The customer’s current Loyalty point balance is 185.

image
image746×440 19.1 KB

However, when inspecting the webhooks:

image
image1471×301 32.1 KB

  • The webhook with event_id: 663d3de2-67b8-3d0c-b0d8-b604d93f08f8, created at 2025-08-22T23:14:25Z, reports the balance as 185.

  • Surprisingly, the next webhook, with event_id: 65b86eac-b0f5-3530-a21c-3a92e338eaf8, created just one second later at 2025-08-22T23:14:26Z, reports the balance as 168.

Square Loyalty Account Id: 54ff3e0c-2226-4aa8-9c9e-4fbb4e32e712

Could you please help clarify:

  1. Why the webhook received later (23:14:26Z) contains an outdated balance?

  2. Is there any scenario where webhook events might be delivered out of sequence, or contain stale data?

  3. Could this be an artifact of retry logic, eventual consistency, or internal queuing?

Understanding this behavior is critical for accurately tracking loyalty balance changes on our end.

Thank you in advance for your insight and assistance!

Best regards,

Murphy

2

:waving_hand: I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:

Additional Documentation

Create and Retrieve Loyalty Accounts
Use Webhooks to Integrate with a Payroll System
Adjust Loyalty Points for a Buyer (Walkthrough 2)

If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.

3

Hi Murphy,

Thank you for reaching out with your observations regarding the loyalty.account.updated webhook payloads. Let’s address your concerns:

  1. Outdated Balance in Webhook: The discrepancy you’re observing, where a later webhook shows an outdated balance, could be due to the asynchronous nature of webhooks and the internal processing of events. It’s possible that the event showing a balance of 168 was processed and queued before the event showing a balance of 185, but due to network or processing delays, it was delivered later.

  2. Out-of-Sequence Delivery: Webhook events can sometimes be delivered out of sequence due to network latency, retries, or internal queuing mechanisms. While Square aims to deliver webhooks in the order they are generated, external factors can occasionally lead to out-of-order delivery.

  3. Retry Logic and Eventual Consistency: Square’s systems are designed with eventual consistency in mind, meaning that while the system will eventually reflect the correct state, there might be brief periods where data appears inconsistent. Retry logic can also contribute to this if a webhook delivery fails and is retried later, potentially after subsequent events have already been processed and delivered.

To ensure accurate tracking of loyalty balance changes, it’s important to handle webhook events idempotently and consider implementing logic to reconcile any discrepancies by periodically querying the current state of the loyalty account directly from the Square API.

I hope this helps clarify the situation. If you have further questions or need additional assistance, feel free to ask.

Best regards,
[Your Name]

This answer was reviewed by @Bryan-Square.