LBLetBuyy Developers
OAuth and webhooks

Install apps and trust lifecycle events

These docs match the active app-store routes, app-engine scope planning, auth-core token contracts, and webhook-service HMAC dispatcher.

Live contract

Authorization code

A merchant authorizes a published app through `/v1/app-store/apps/:id/oauth/authorize`. The gateway verifies store ownership, requested scopes, and redirect URI before upserting an active installation.

  • Grant type is `authorization_code`.
  • Authorization codes are short lived and expire after 15 minutes.
  • The response includes `redirect_to`, `code`, `state`, granted scopes, app id, installation id, and store id.
Live contract

Access token exchange

`POST /v1/app-store/oauth/token` exchanges the authorization code for a scoped app access token after checking client id, redirect URI, active installation, and one-time code redemption.

  • Token response includes `access_token`, `token_type`, `expires_in`, `expires_at`, `scope`, and `scopes`.
  • Auth-core signs app access tokens as JWTs with normalized scopes.
  • The installation config stores token hashes, not raw returned tokens.
Live contract

Embedded token exchange

`POST /v1/app-store/oauth/token-exchange` exchanges an authenticated merchant session for an embedded app token tied to an installation and store.

  • Requires protected merchant auth middleware.
  • Validates active installation and store ownership.
  • Used by embedded app surfaces and the app bridge fetch contract.
Webhook verification

HMAC over timestamp and raw body

The dispatcher sends `X-LetBuyy-Timestamp`, `X-LetBuyy-Hmac-SHA256`, event id, event type, request id, and trace id.

const payload = timestamp + "." + rawBody;
const expected = hmacSha256Hex(signingSecret, payload);
const actual = header.replace(/^v1=/, "");
return timingSafeEqual(expected, actual);
Live contract

HMAC signing

App lifecycle webhooks are sent by `services/webhook-service` and signed with the `X-LetBuyy-Hmac-SHA256` header.

  • Signature payload is `X-LetBuyy-Timestamp + '.' + rawBody`.
  • Header value is versioned as `v1=<hex-hmac>`.
  • The legacy `X-LetBuyy-Signature` header is also sent for compatibility.
Live contract

Delivery headers

Webhook deliveries include event, request, trace, and timestamp metadata so receivers can verify, deduplicate, and correlate processing.

  • Headers include event id, event type, request id, trace id, timestamp, and HMAC signature.
  • Webhook targets must be HTTPS in staging and production.
  • The service records response status, a response preview, and request errors.
Live contract

Compliance topics

App-engine always includes mandatory compliance topics when planning app webhook subscriptions.

  • `customers/data_request`
  • `customers/redact`
  • `shop/redact`
Live contract

Retry operations

Operational retry and dispatch controls are exposed through `/v1/operations` webhook-delivery and outbox endpoints.

  • `POST /v1/operations/webhook-deliveries/dispatch` dispatches pending deliveries.
  • Outbox dispatch and dead-letter replay endpoints exist for operations users.
  • Developer self-serve retry APIs are not exposed yet.