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 |
