Reference

Security model

Direction	Auth	Detail
Inbound (you → Vambe)	HMAC-SHA256	Sign `{timestamp}.{rawBody}` with your `signing_secret`; send `x-vambe-signature` + `x-vambe-timestamp`. 5-minute freshness window.
Outbound (Vambe → you)	Bearer token	Vambe sends `Authorization: Bearer {merchant access_token}` + `X-Vambe-Store-Id`.
OAuth state	Encrypted	The `state` parameter is encrypted by Vambe; echo it back unchanged.
Secrets at rest	AES-256	Your `client_secret` and the app `signing_secret` are encrypted at rest.

Rotate your signing secret anytime with POST /api/ecommerce-app/{id}/rotate-secret. The new secret is returned once; update your webhook signer before the old one stops being used.

Outbound URL requirements

HTTPS only.
Must resolve to a public IP — private, loopback and link-local addresses are blocked (SSRF protection).
Respond within ~15 seconds.

App lifecycle

State	Visible to	Editable	Receives events
`draft`	Creator	Yes	Yes (creator’s own installs)
`pending_review`	Creator	No	Yes
`approved`	All accounts	No	Yes
`rejected`	Creator	Yes (→ draft)	No
`suspended`	Nobody	No	No

Event types

Inbound (`capabilities.inbound_events`)

Event	Endpoint
`order`	`POST /api/public/apps/{appId}/events/order`
`checkout`	`POST /api/public/apps/{appId}/events/checkout`
`fulfillment`	`POST /api/public/apps/{appId}/events/fulfillment`
`product`	`POST /api/public/apps/{appId}/events/product` and `…/product/delete`

Outbound (`capabilities.outbound`)

Capability	Tool it powers
`order_get`	Live order status (“where is my order?”)
`stock_get`	Stock by location
`checkout_create`	Checkout link generation
`products_list`	Reserved — catalog pull (coordinate with Vambe)

Supported currencies

ISO codes accepted in currency / total_price / price fields:

CLP, USD, MXN, BRL, UF, ARS, COP, UYU, PEN, EUR, HNL, BOB, PYG,
GTQ, NIO, PAB, CRC, DOP, VES, BZD, SRD, GYD

Operational notes

Idempotency. Orders, checkouts, fulfillments and products upsert on their external id — safe to retry. Always retry on non-2xx; webhooks may be redelivered.
Product sync is incremental. A product webhook only affects the product it carries; it never deletes the rest of your catalog.
Multi-store resolution depends on account_info_url populating external_id. Without it, only single-installation apps resolve automatically.
Graceful degradation. If an outbound capability is missing, slow, or errors, the corresponding assistant tool simply returns no data — it does not break the conversation.

Endpoint cheat-sheet

Method	Path	Auth	Who
`POST`	`/api/ecommerce-app`	`x-api-key`	Provider
`PATCH`	`/api/ecommerce-app/{id}`	`x-api-key`	Provider
`POST`	`/api/ecommerce-app/{id}/submit`	`x-api-key`	Provider
`POST`	`/api/ecommerce-app/{id}/rotate-secret`	`x-api-key`	Provider
`GET`	`/api/ecommerce-app/available`	`x-api-key`	Merchant
`GET`	`/api/public/apps/oauth/callback`	OAuth state	Provider redirect
`POST`	`/api/public/apps/{appId}/events/{event}`	HMAC	Provider

Get started

Integration contract

App management API

Webhook API

Security model

Outbound URL requirements

App lifecycle

Event types

Inbound (`capabilities.inbound_events`)

Outbound (`capabilities.outbound`)

Supported currencies

Operational notes

Endpoint cheat-sheet

​Security model

​Outbound URL requirements

​App lifecycle

​Event types

​Inbound (capabilities.inbound_events)

​Outbound (capabilities.outbound)

​Supported currencies

​Operational notes

​Endpoint cheat-sheet

Security model

Outbound URL requirements

App lifecycle

Event types

Inbound (`capabilities.inbound_events`)

Outbound (`capabilities.outbound`)

Supported currencies

Operational notes

Endpoint cheat-sheet