ShrubberyDocs
Sign in

Inbox (API)

Definition

The webhook endpoint POST /api/v1/inbox that allows external systems to create Shrubbery rows programmatically. An Inbox call produces a Pending_Handshake row immediately — the assignee receives a Nudge and sees it in the Accord without any further Lead action.

Avoid: webhook (technically correct but ambiguous — prefer "Inbox endpoint" or "Inbox API"). Do not confuse with the Accord, which is the Knight's in-app inbox.

Role

The Inbox API is the fully automated capture path. An external system (Jira, Linear, GitHub, a custom script) presents a bearer API Token and provides the assigner email, assignee email, objective, deadline, and optional external mapping. The endpoint creates the row as Pending_Handshake in one step: no Draft review, no Lead promotion required. Inngest immediately fires a Nudge to the assignee through their preferred channel.

The token owner is recorded as the assigner. The assignerEmail field in the payload exists for audit readability only; the resolved user must match token.user_id — a token cannot create rows on behalf of another Lead.

Each Inbox row stores (external_system, external_id) for deduplication. The uniqueness constraint (external_system, external_id, assigner) makes the endpoint safe to call on every webhook delivery: a replay from the same token returns 409 duplicate_external_ref rather than creating a duplicate.

Lifecycle

Not a stateful concept — the Inbox API is an entry point, not an entity.

  1. External system calls POST /api/v1/inbox with a bearer token.
  2. verifyBearer validates the token and extracts user_id (the assigner).
  3. A Pending_Handshake row is inserted with source = inbox_api and (external_system, external_id) stored.
  4. Inngest fires a handshakeRequestedEvent → Nudge delivered to the assignee.
  5. Knight sees the row in the Accord and accepts or refuses.

Last updated: 22 June 2026