Webhooks

Webhooks are the preferred way to get data to AVA Golf, for rounds and sessions alike. They eliminate polling and give golfers near-instant access to what they just played.

POST{your_callback_registration_endpoint}

Register a webhook URL where your system notifies AVA Golf of lifecycle events.

Tip

Webhooks plus a backfill path (date-range filtering on GET /rounds or GET /sessions) give us both near-real-time updates and the ability to recover history when a user first connects.

Lifecycle events

Event	Sent when	Requirement
round.completed	A round is finished and saved.	Required
round.edited	The user modifies a past round, e.g., corrects a score or moves a shot.	Strongly recommended
round.deleted	The user removes a round.	Strongly recommended
session.completed	A practice session is finished and saved.	Required
session.edited	The user modifies a past session.	Strongly recommended
session.deleted	The user removes a session.	Strongly recommended

Edit & delete events matter

Without edit and delete events, stale data persists and must be corrected through AVA Golf — or all data must be re-synced via REST endpoints. These events are important for data integrity.

Payload styles

Two payload styles are supported — choose whichever fits your architecture:

1. Full payload: The webhook body contains the complete round (with holes and shots) or session (with all shots). Preferred when feasible.
2. Notification + fetch: The webhook body contains the round or session ID (and optionally a callback URL); AVA Golf retrieves the full data via your REST endpoints. This is equally acceptable — it is how several of our production integrations work.

Signatures

Every payload should include an HMAC signature header (or equivalent) so we can verify it came from you.

Account webhooks

Strongly recommended.

Deregistration

Notify us when a user disconnects their account so we can clean up authorization state promptly. We actively rely on this in production integrations.

Permission changes

Notify us when a user changes data-sharing permissions so we can adjust our sync behavior.

Idempotency keys

A nice-to-have: include an X-Idempotency-Key header on webhook payloads so we can safely deduplicate retries without reprocessing.

Round trackers can also push a round hole by hole while it’s played; see live scoring.