API keys, rate limits and webhooks

Moonbase's API lets your own systems do what you'd otherwise do in the dashboard: issue licenses from your web shop, publish releases from your build pipeline, or look up a customer from your helpdesk. API keys let those systems in, and webhooks tell them the moment something happens. This article covers the setup in Moonbase. The reference for every endpoint and event is in our API documentation.

Everything here is under Account settings > Developer, which people with the Developer or Admin role can open (see Team members and roles).

Your account details

At the top of the Developer tab, Account details lists what your integrations need to talk to Moonbase:

• API endpoint: your account's own address, such as https://acme-audio.moonbase.sh.

• Account ID: the identifier your apps, SDKs and integrations are set up with.

• Public key: what your apps use to check that a license really comes from Moonbase, for example when validating it offline.

API keys

Creating a key

Under API Keys, click Create key, give the key a Name that says what it's for, and choose its Access:

• Full access: everything the API can do, including areas we add later.

• Restricted: only the areas you choose, each with None, Read or Read & write. Read & write includes reading.

The areas are Products (with releases and release file uploads), Customers, Orders (with checkouts and refunds), Subscriptions, Licenses, Activations, Trials, Coupons, Vouchers and Affiliates, plus Campaigns and Automations on accounts where those betas are switched on. A request needs the area of whatever it reads or changes: listing a customer's orders needs Orders, for example, and revoking a license's activation needs Activations.

We recommend giving every key only what it needs. A build pipeline that publishes releases needs nothing more than Read & write on Products, and a helpdesk that looks customers up gets by with Read on Customers, Orders and Licenses. A restricted key is refused anything it hasn't been granted, including areas we add to Moonbase later, and the refusal says what is missing, such as "does not have write access to orders".

Click Create, and copy the key straight away. It starts with mb_ and is shown in full only this once: after that, the list shows just its first characters. A lost key can't be recovered, so create a new one and remove the old.

Managing your keys

The list shows Full access or Restricted under each key's name. Access on a key's row shows its areas and lets you change them, and the very next request with that key uses the new access. Remove deletes a key and stops it working immediately.

Rate limits

To keep Moonbase fast for everyone, the API limits how many requests it accepts: per IP address for requests without an API key, and per key for requests with one. A request over a limit is refused with 429 Too Many Requests, and its Retry-After header says how many seconds to wait. The limits are listed in the API documentation.

Preparing for a launch

Limits usually show up on launch day, when a website's own server calls Moonbase for its visitors (submitting a sign-up form, say) without an API key. Every customer then arrives from the server's one address and shares the limits of a single visitor. So before launch day, make sure your server sends your API key with every request it makes to Moonbase, including the ones it makes for your customers. And if you expect more traffic than the limits allow, get in touch with us a few days ahead.

Webhooks

Webhooks tell your own systems the moment something happens in Moonbase, so they never have to keep asking. Moonbase sends the details of each event to your endpoint.

Creating a webhook

Under Webhooks, click Create webhook, and fill in a Name, an optional Description, the Endpoint and the Events to send. The endpoint has to use HTTPS and be reachable from the internet, so localhost and addresses on a private network won't work.

You can choose events for orders, licenses, trials, releases, subscriptions, vouchers and customers. The webhooks documentation lists every event, with what each one sends.

Edit lets you change a webhook, pause it with the Active switch without deleting it, or set a new Secret Key. Remove deletes it.

Posting to Discord

Paste a Discord webhook URL as the endpoint, and Moonbase posts nicely formatted messages to that channel instead of raw data. It's an easy way to celebrate every sale with your team.

Checking that a webhook came from Moonbase

Every delivery is signed with the webhook's secret key, in an X-Signature header, so your endpoint can check that it really came from Moonbase. The secret key starts with mb_ and is shown in full only when you create the webhook. The webhooks documentation shows how to check the signature.

Logs and retries

Logs on a webhook's row lists every delivery, with what Moonbase sent and how your endpoint answered:

If your endpoint doesn't answer with a 2xx status, or can't be reached, Moonbase tries again three more times within about 15 seconds. After that, the delivery is marked as failed and isn't tried again on its own, but a failing webhook is never switched off. Once your endpoint is fixed, click Retry on the failed delivery to send it again. A retry only goes out while the webhook is Active and still sends that event.

Now and then, the same event can arrive twice, so make sure your endpoint handles that.

Frequently asked questions

I've lost my API key.
Keys can't be shown again. Create a new key, update your systems to use it, then remove the old one.

Which key should my build pipeline use to publish releases?
A restricted key with Read & write on Products. Our guide to publishing releases from GitHub Actions walks through the rest.

Why didn't my webhook fire?
Check that the endpoint uses HTTPS and is public, that the webhook is Active, and that the event is ticked. Logs shows every attempt and the answer your endpoint gave. Orders, customers and licenses you import never trigger webhooks.

Can I connect Slack or Zapier?
There's no built-in Slack or Zapier integration today. Webhooks are the way to send Moonbase events elsewhere, and Discord webhook URLs work directly.