--- title: "API keys and webhooks" description: "The settings screen where you generate API keys, register webhook endpoints and find your tenant ID—what each field does, the things that catch people out, and how developer mode shows the API behind the dashboard." lastModified: "2026-10-15" lang: "en" wordCount: 1962 url: https://qualyhq.com/training/settings/api-keys-and-webhooks --- ## Site navigation - [For schools](/international-education/for-schools.md) — For international education schools - [For agents](/international-education/for-education-agents.md) — For international education agents - [Explore](/training.md) — Watch videos on how to use Qualy - [About](/about.md) — Learn about Qualy's mission and values - [Pricing](/pricing) - [5-min demo](/demo.md) - [Login](https://dashboard.qualyhq.com) # API keys and webhooks > For developers integrating Qualy with other systems. ## At a glance - **Intended for:** Super admins - **Available in:** All plans - **Reading time:** 6 minutes - **Last updated:** 15th October 2026 ## Quick summary Go to Settings → Add-ons & integrations → API keys & webhooks to generate a key, register webhook endpoints for the events you need, and find your tenant ID. A new key gets full admin access by default and stays visible in this list for as long as it exists—there is no one-time reveal, so treat this page as sensitive as the key itself. Saving a webhook only works if your destination URL answers the one-time verification challenge first, which is why most first attempts fail. Send the tenant ID as the X-TENANT-ID header on every request. Developers can also turn on Developer mode in their profile to see the API request and response behind payments, transactions and splits, and a live log of the calls the dashboard makes—no super admin access needed for that part. ## Overview **Settings → Add-ons & integrations → API keys & webhooks** is the developer control panel: three blocks on one screen, covering API keys, webhook endpoints and your tenant ID. It is restricted to super admins—anyone else sees the row greyed out with a lock. This page covers what the screen does. If you are still working out *whether* to build an integration at all — and which of the four routes fits — read [Integrating with your own systems](/training/integrations/integrating-with-your-own-systems.md) first. ## API keys **Generate** an API key here to authenticate calls to the Qualy API from your own systems — name it, click **Add new**, and it appears in the list below with the key itself shown in full. A new key gets **full admin access** to your account, the same as a super admin user. There is no role picker on this screen. If you need something narrower, create the key through the API instead and set its roles there — noting that an API key cannot create another API key, so the call has to come from a signed-in super admin. Keys are not shown once and then hidden. The full value stays visible in this list for as long as the key exists, which is different from how many API platforms handle it — so anyone who can open this page can read every active key. Click **Remove** to revoke one immediately, whether that's for rotating credentials or cutting off a contractor's access once their work is done. ![The API keys & webhooks page, showing an active key, an empty webhooks list, and the tenant ID](/images/training/settings/api-keys-and-webhooks/01-api-keys-page.png) ## Webhooks Create a **webhook** so Qualy calls your endpoint when something happens, instead of your system asking the API over and over whether anything changed. Click **Add new** and fill in three fields: a destination URL (HTTPS), a secret you generate yourself, and the events to send. The secret is used to sign each payload with HMAC-SHA256 so you can verify the call came from Qualy. The events selectable here: - contacts.create - contacts.update - paymentIntents.create - paymentIntents.update - paymentIntents.delete - partnerships.create - partnerships.update - splitIntents.create - splitIntents.update - splitIntents.delete - transactions.create - transactions.update - ingest.job.completed - ingest.job.review - ingest.job.partial - ingest.job.failed - ingest.job.cancelled - ingest.task.failed The six `ingest.*` events cover AI document ingestion: the job-level ones fire when an ingest job reaches a terminal state (completed, waiting on your review, partially completed, failed, or cancelled), and `ingest.task.failed` fires when a single task inside a job has exhausted its retries. ![The create webhook form filled in with a destination URL and two payment events checked](/images/training/settings/api-keys-and-webhooks/03-create-webhook-filled.png) Saving will fail unless your destination URL passes the **one-time verification challenge**. Qualy sends a GET request carrying a `validationToken` query parameter, and your endpoint has to return that token as plain text before the webhook is created. So the URL needs to answer GET as well as POST. This is the reason most first attempts don't save — it's documented with a code example under [Setting up webhooks](https://docs.qualyhq.com/docs/webhooks). If deliveries keep failing, or your endpoint stops replying for more than 24 hours, Qualy deactivates the webhook and emails your super admins. Events generated while it was off are discarded rather than queued, so nothing arrives late once you fix it — repair the endpoint, create the webhook again, and pull the gap from the API. ## Tenant ID Your **tenant ID** identifies your Qualy account. You'll find it at the bottom of this page, formatted like `eu1-hrxonyxppzfqvypuekggjobz`. Include it on every request, as the `X-TENANT-ID` header, next to the API key in the `Authorization` header (`ApiKey` followed by the key). The header is what points a request at your account's data. Leave it out and the request doesn't reach your account, which is the most common way a first integration ends up reading nothing at all — so hand the tenant ID to whoever is building against the API along with the key. Qualy's [developer documentation](https://docs.qualyhq.com/docs) covers authentication, endpoints, error codes and worked examples. Most training guides link to the relevant API docs where a task can be done programmatically instead of by hand. ## Developer mode: the API behind the dashboard The dashboard calls the same `/v1` endpoints, with the same payloads, that your integration will — so the fastest answer to "how do I do this through the API?" is to do it once in the dashboard and look at the call it made. **Developer mode** shows you that. It's a per-person setting, and it needs no special role. There are two ways to turn it on: - **When the person is invited.** Tick **Mark as a developer** on the invite, under the name and email fields. - **From their own profile.** Click your picture in the top right, open **Account preferences**, tick **Developer mode** in the **Date, time and language preferences** card and click **Save**. Their permissions stay exactly as they were. With it on, two things appear. **API details on a record.** On a payment, a transaction or a payment split, the options list shows **API details** among the everyday options. Without developer mode the same panel is still there, named **Technical information**, down in the **Danger zone** with the destructive actions. It shows the endpoint that returns the record, the request as ready-to-run **cURL**, **Node** or **PHP**, the live response, and the related endpoints — the payment behind a transaction, the splits on a payment — which open in place. Endpoints your roles can't call say so, with the role they need. Every snippet carries your tenant ID as `X-TENANT-ID` and reads the key from a `QUALY_API_KEY` variable rather than printing one. **The API activity bar.** A bar along the bottom of the dashboard lists the calls the dashboard makes as you work: time, method and path, status and how long it took. Click it to open the list, then click a call to see its request (written as a cURL command you can **Copy**) and its response (**Copy JSON**). Filters in the query string are shown decoded; **View URL-encoded** shows them as they're sent. The activity bar shows calls *your* dashboard just made, not your integration's traffic. It keeps the last 50 calls in that browser tab only — nothing is saved, and reloading the page clears it. Sign-in calls, passwords and tokens are never recorded, and neither are calls to add-ons or the compliance file. The copied request never carries a credential: it reads the key from a `QUALY_API_KEY` variable, so set that to your own API key before you run it. To switch it off, untick **Developer mode** in your profile, or use **Turn developer mode off** under **Why am I seeing this?** in the bar itself. The bar's links to **Your API keys** only open for super admins, because the keys page is theirs. ## Frequently asked questions ### Where do I manage API access? In Settings → Add-ons & integrations → API keys & webhooks. That one page covers generating API keys, creating webhooks, and finding your tenant ID for integration. ### What is an API key for? It authenticates requests to the Qualy API so your own systems can read and create data programmatically, without a person signing in. ### What access does a new API key have? Full admin access to your account, the same as a super admin user. The dashboard has no role picker on this screen—if you need scoped access, create the key through the API instead and set its roles there. One limit worth knowing: an API key cannot create another API key, so that call has to be made by a signed-in super admin. ### Who can open this page? Super admins only. Everyone else sees the API keys & webhooks row on the Settings page greyed out with a lock, and the screen itself is restricted to the admin:super role. If a developer needs to set up a key or webhook, a super admin has to do it or grant them super admin access for the job. Developer mode is different: it needs no special role, and shows a developer the API behind the records they can already see. ### Can I see my key again after I create it? Yes. Unlike a lot of API platforms, Qualy keeps showing the full key in this list for as long as it exists, not just once at creation. That also means anyone who can open this settings page can read every active key, so guard access to the page accordingly. ### What are webhooks? They let Qualy call your systems when events happen—a payment created, a split updated, a contact added—so your software reacts automatically instead of asking the API over and over whether anything changed. For how they behave in practice (ordering, duplicates, signing), see Integrating with your own systems. ### Why did creating my webhook fail? Almost always the one-time verification challenge. Before saving a webhook, Qualy sends a GET request to your destination URL with a validationToken query parameter, and your endpoint has to return that token as plain text. If it does not, creation fails. Your URL therefore needs to answer both GET and POST requests, and it must be HTTPS. ### Why did my webhook stop sending? Qualy deactivates a webhook endpoint that keeps failing or stops replying for more than 24 hours, and emails your super admins when it happens. Events generated while it was inactive are discarded rather than queued, so nothing is backfilled once you fix it—fix the endpoint, create the webhook again, and pull whatever you missed from the API. ### What is the tenant ID? An identifier for your Qualy account, formatted like eu1-hrxonyxppzfqvypuekggjobz. Send it as the X-TENANT-ID header on every API request, alongside your API key in the Authorization header as ApiKey followed by the key. The header is what points the request at your account's data—leaving it out is the most common reason a first integration gets empty or wrong results. ### How do I find the API call that does what I just did in the dashboard? Turn on Developer mode. Click your picture in the top right, open Account preferences, tick Developer mode and save. An API activity bar then appears along the bottom of the dashboard, listing every call the dashboard makes as you click—method, path, status and time—and each call opens into its request and response. The dashboard uses the same /v1 endpoints and payloads your integration would, so copying the request gives you a working starting point; add your own API key before running it. ### Is there documentation? Yes. Qualy's developer docs cover endpoints, examples and how-tos, with a link from this settings page and throughout these guides. ### Can I revoke a key? Yes. Click Remove next to the key to revoke it immediately, useful for rotating credentials or cutting off a contractor's access once their work is done. ## Build with the Qualy API Everything you need to integrate—endpoints, examples and guides. [View API Docs](https://docs.qualyhq.com/docs) ## More on Qualy **Industries** - [For schools](/international-education/for-schools.md) — For international education schools - [For agents](/international-education/for-education-agents.md) — For international education agents **Support** - [Training](/training.md) - [System status](https://qualyhq.statuspage.io/) — Qualy system status - [Product updates](https://changelog.qualyhq.com) — As we work on Qualy, here we spotlight what we’ve learned and updated across our products - [Contact](/contact-us.md) **Product** - [Demo](/demo.md) - [Enterprise](/enterprise.md) - [Testimonials](/testimonials.md) — Learn what some customers have to say about Qualy - [About](/about.md) — Learn about Qualy's mission and values - [Blog](/blog) — International education payments blog by Qualy - [Trust center](/trust.md) - [API](/api.md) — Qualy API for international education payments - [Zapier](/integrations/zapier.md) — Connect Qualy to 7,000+ apps with Zapier - [NexPay](/nexpay.md) — Qualy + NexPay — automate everything around the payment **Legal** - [General terms](/terms-and-conditions.md) - [Payer terms](/terms-for-payers.md) - [Privacy policy](/privacy-policy.md) - [Service levels](/sla.md) - [Accessibility](/accessibility.md) - [Legal & compliance](/trust.md)