API & webhooks

Push data into OnGravy with the /api/v1 REST API, get data out the moment it changes with HMAC-signed webhooks, and extend the product itself through the plugin marketplace. This chapter covers authentication, the v1 resources, webhook signing and retries, and how to connect an AI assistant over MCP. The developer portal has the full machine-readable reference.

Authentication & API keys

1. Go to Settings → API keys and create a key.
2. Choose a scope — read, write, or admin — and an expiry from the presets. Least privilege wins: a reporting integration needs only read.
3. Copy the raw key immediately. It is shown once — OnGravy stores only a SHA-256 hash, so it cannot be re-displayed later.

Send the key on every request, either way works:

Authorization: Bearer ogv_...        # preferred
x-api-key: ogv_...                   # alternative

Verify credentials with the whoami endpoint — it echoes the resolved business and scope:

GET /api/v1/ping
→ { "ok": true, "businessId": "…", "scope": "read", "version": "v1" }

The v1 REST API

The current v1 surface is deliberately small and stable:

Reading invoices

GET /api/v1/invoices?status=&from=&to=&limit=

Creating invoices

POST /api/v1/invoices is designed so external systems (a POS, a booking engine, a storefront) can push sales with minimal ceremony. You do not need OnGravy IDs up front — the API resolves references in a fixed ladder and auto-creates what it cannot find:

• Party resolution: id → phone → exact name match → auto-create the party.
• Item resolution: item_id → exact name match → auto-create the item.

GST is always computed server-side. Whatever tax figures the caller sends, OnGravy derives the GST treatment from the party, items and place of supply — so a buggy upstream system cannot file wrong tax through the API.

Specs, SDKs & the developer portal

• OpenAPI spec — /api/openapi.json, always current with the deployed API.
• Postman collection — /api/postman.json, import and go.
• Developer portal — /developers for the guided reference; in-app, /dashboard/developers/sdks lists SDKs and /dashboard/developers/apps manages your registered apps.

Outbound webhooks

Webhooks push events to your systems the moment they happen — the inverse of polling the API.

1. Go to Settings → Webhooks and add your endpoint URL. HTTPS only — plain HTTP endpoints are rejected.
2. Subscribe the endpoint to specific events, or to all events.
3. Store the endpoint secret shown at creation — you need it to verify signatures.

Every delivery carries two headers and a consistent envelope:

X-OnGravy-Event: invoice_paid
X-OnGravy-Signature: sha256=<hex>

{
  "event": "invoice_paid",
  "timestamp": "…",
  "business_id": "…",
  "delivery_id": "…",
  "data": { … }
}

The signature is an HMAC-SHA256 of the raw request body using your endpoint secret. Compute it on your side and compare (constant-time) before trusting the payload.

For human-facing notifications in Slack or Teams, use notification channels instead — see Integrations.

Plugin marketplace

Plugins extend OnGravy from the inside. Users install them from /dashboard/marketplace; builders start from the publisher guide at /dashboard/developers/marketplace-guide.

• Sandboxed runtime — plugin code runs isolated from the core app and other tenants.
• Validator DSL — declare data-validation rules declaratively rather than shipping arbitrary code for the common cases.

Connect your AI assistant (MCP)

OnGravy ships an MCP server, so any AI assistant that speaks the Model Context Protocol can work with your books as tools — querying data and drafting actions under your account’s permissions. Set it up from settings: look for the connect-your-AI-assistant entry, which walks through issuing the connection credentials.

Gotchas & good to know

• The raw API key appears exactly once. Only the SHA-256 hash is stored; lose the key and you create a new one, full stop.
• limit caps at 200. Asking for more silently gives you 200 — paginate rather than raising the number.
• Auto-create is a feature and a footgun. Party/item names that don’t exactly match an existing record create a new record. Send IDs (or phone numbers for parties) when you have them to avoid duplicates.
• Server-side GST is non-negotiable. Don’t compute tax upstream and expect it to stick — send the commercial facts and let OnGravy derive the tax.
• Verify webhook signatures on the raw body. Re-serialising the JSON before computing the HMAC is the classic verification bug — the signature covers the bytes as delivered.
• Answer webhooks fast. You have 10 seconds; acknowledge with a 2xx and process asynchronously. Use delivery_id to de-duplicate, since retries mean at-least-once delivery.
• Webhook endpoints must be HTTPS — this is enforced, not advisory.
• Events fired by automations (Autopilot decisions, agent actions) flow through the same webhook pipe — see Automation for what emits what.