ShrubberyDocs
Sign in

Sync (API)

Definition

The webhook endpoint POST /api/v1/sync that allows external systems to push status updates — completed or refused — back to an existing Shrubbery row, identified by its (external_system, external_id) pair.

Avoid: status webhook, completion webhook.

Role

The Sync API closes the loop between Shrubbery and external trackers. When a Jira ticket is closed, a Linear issue is resolved, or any external system signals a terminal state, a POST /api/v1/sync call transitions the linked Shrubbery without any human action in-app.

The endpoint looks up the target row by (external_system, external_id) scoped to the token owner's user_id — a token from one Lead cannot close another Lead's rows. The resulting audit event records actor_kind = api_token, so the Dossier shows who (or what) closed the row. The Commitment Flow Score treats API-originated completions identically to user-originated ones.

Lifecycle

Not a stateful concept — the Sync API is a state-transition entry point, not an entity.

  1. External system calls POST /api/v1/sync with a bearer token, external_system, external_id, and status (completed or refused).
  2. verifyBearer validates the token; endpoint resolves the matching Shrubbery row.
  3. State transition is applied: Active → Completed or Active → Refused.
  4. Audit event written with actor_kind = api_token.

Last updated: 22 June 2026