Skip to main content
By the end of this page you’ll have made your first authenticated call, listed the locations your app can reach, and received a real signed webhook at your own endpoint — all in test mode, against isolated data you can’t break.

​
Before you begin

You need a sandbox API key (mpk_test_…). The Maple team issues one when they create your developer app during onboarding. If you don’t have one yet, contact us — it takes us a few minutes. That’s the only prerequisite. There’s no SDK to install; every example here is plain curl you can paste into a terminal. You’ll work against the sandbox the whole way — isolated data you can’t break. (Production lives at https://api.maple.inc/v1; see Environments.)
Keep your key and the sandbox base URL in environment variables so you can copy the examples verbatim:
export MAPLE_KEY="mpk_test_..."
export MAPLE_BASE="https://api.staging.maple.inc/v1"
1

Confirm the API is reachable

/ping needs no credential. A clean response means your network can reach Maple.
curl $MAPLE_BASE/ping
Response
{ "object": "developer_api_status", "status": "ok", "version": "..." }
2

Make your first authenticated call

GET /v1/me echoes back the app your credential belongs to, the environment it operates in, and the scopes it holds. It’s the fastest way to confirm a key works.
curl $MAPLE_BASE/me \
  -H "Authorization: Bearer $MAPLE_KEY"
Response
{
  "object": "developer_app",
  "id": "dap_...",
  "name": "Your Integration",
  "environment": "test",
  "scopes": ["locations:read", "connections:write", "orders:read", "orders:write", "webhooks:write"]
}
environment reads test. A test key can only ever see test data — nothing you do here touches a live merchant.
If you get a 401, the key is missing, malformed, or inactive. See Errors.
3

List the locations you can reach

Each restaurant your app integrates is a location a merchant has granted you access to. List the ones you can see:
curl $MAPLE_BASE/locations \
  -H "Authorization: Bearer $MAPLE_KEY"
Response
{
  "object": "list",
  "data": [
    { "object": "location", "id": "str_test_123", "name": "Maple Test Kitchen", "status": "active", "timezone": "America/New_York", "...": "..." }
  ]
}
During onboarding we grant your test app at least one test location to build against. Note its id.
4

Connect to a location

A grant lets you see a location. A connection makes your app its order receiver — orders only route to you after this call.
curl -X POST $MAPLE_BASE/locations/str_test_123/connection \
  -H "Authorization: Bearer $MAPLE_KEY"
Response
{ "object": "connection", "location_id": "str_test_123", "status": "active", "...": "..." }
Connections are exclusive per environment: if another app already holds the location, you get a 409. Read How Maple works for the full grant-versus-connection model.
5

Receive your first signed webhook

Register an HTTPS endpoint you control. (For local testing, a tunnel such as ngrok or Cloudflare Tunnel gives you a public URL.)
curl -X POST $MAPLE_BASE/webhook_subscriptions \
  -H "Authorization: Bearer $MAPLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_url": "https://your-app.example.com/maple/webhooks",
    "event_types": ["order.notification"]
  }'
The response includes a one-time signing secret (mwhsec_…). Store it now — it is never shown again.
Response
{
  "object": "webhook_subscription.created",
  "subscription": { "object": "webhook_subscription", "id": "dws_...", "status": "enabled", "...": "..." },
  "signing_secret": "mwhsec_..."
}
Now fire a synthetic delivery to that endpoint to confirm it’s wired up:
curl -X POST $MAPLE_BASE/webhook_subscriptions/dws_.../test \
  -H "Authorization: Bearer $MAPLE_KEY"
Response
{ "object": "webhook_test_result", "event_id": "evt_...", "delivered": true, "response_status": 200 }
delivered: true with a 2xx response_status means Maple reached your endpoint and it accepted the event. You’re receiving webhooks.

​
You just did the whole loop in miniature

Authenticate, find a location, connect to it, and receive a signed event — that’s the spine of every Maple integration. Everything else is filling it in.

​
Where to go next

Receive and decide orders

Verify webhook signatures and drive real orders with accept / deny / ready / complete.

Publish a menu

Push a location’s menu so the items in your orders map to your own IDs.

Webhooks in depth

Signature verification, delivery guarantees, retries, and replay.

Authentication

API keys, environments, and scopes.