API keys and webhooks

Do you need them?

Probably not, if you use ConfigCheckup through its own screens, emails and the Teams or Slack alerts under Settings. Consider them when you want to:

• show tenant scores and findings in your own dashboard or reporting tool;
• start an assessment from a script or another system, for example after onboarding a tenant;
• draft a fix from your PSA or a script, for someone to approve in ConfigCheckup;
• send an alert somewhere ConfigCheckup does not post to directly, such as a ticketing flow or an automation platform.

If none of those apply, you can ignore this part of Settings.

API keys

An API key is like a password for a program. Whatever holds the key can read your workspace’s tenants, assessments, findings, reports, changes, baselines, alerts, licences, devices and audit log, and export any table you can export in the console, so treat it with the same care as an admin password. You can limit a key to some tenants, and to your own IP addresses.

Create one

1. 1In ConfigCheckup, go to Settings → API and webhooks. You need the Admin or Owner role.
2. 2Name the key after what will use it, for example “Power BI” or “Onboarding script”, so you know what breaks if you revoke it.
3. 3Choose what it can do. Read is always included; add Queue assessments and reports only if the tool needs to start assessments or make reports (as a PDF or a Word document), and Draft changes for approval in the console only if it needs to draft fixes.
4. 4If the tool only needs some tenants, open Limit it to some tenants or IP addresses and tick them, or add a tag. A key limited this way sees nothing of any other tenant. If the tool always calls from the same place, add its IP address or range too.
5. 5Choose when it expires. Shorter is safer; you can always create another.
6. 6Copy the key straight away. It is shown once; only a fingerprint of it is stored, so it cannot be shown again.

Give the key to whoever is building the connection, along with the API reference, which lists every endpoint.

A key belongs to the person who created it. If they are suspended or removed from the workspace, their keys are revoked at once, so for a connection that must outlive one person, have an Admin or Owner who is staying create the key.

Limiting a key, and seeing what it did

Under each key, Tenants and IP ranges it may use changes its limits at any time; the change applies from its next request. A key limited by a tag follows the tag: a tenant tagged later is included at once, and one untagged is left out at once. In-house teams see the same with their tenants.

A key acts for the member who made it. If that member is limited to some tenants on Settings › Team, the key sees only the tenants that are both its own and theirs, whatever its own limits say, and a change to the member's tenants applies from the key's next request. A member limited to some tenants sees and manages only the keys they made.

Recent requests under each key lists what it asked for in the last 30 days: when, what it asked for (such as GET /api/v1/tenants), and the answer (for example 200 for success, 404 for something it cannot see, 429 when it asked too often). Each request has an id; quote it if you ask us about one. For each request we keep the method and path, the answer, the request id, the IP address it came from and how long it took, for 30 days. We never keep the query string, what was sent or returned, or the key.

Each key may make 120 requests a minute. Lists come a page at a time, and a tool can ask for only what changed since it last looked, so a sync rarely comes near the limit. The API reference shows how.

Drafting changes

A key that may draft changes can turn a finding into a change, the same draft “Fix this” makes in the console, with its dry run against the live tenant. That is all it can do. The draft waits under the tenant’s Changes, and a person sends it for approval, approves it and runs it in ConfigCheckup, with one or two approvers as the tenant is set up. No key approves, runs or rolls back a change. It needs automation switched on for the tenant, and it is recorded in the audit log as made by the key, for the person who created it.

Webhooks

A webhook is the other direction: when something happens, ConfigCheckup sends a short message to a web address you choose. Nothing has to keep asking whether anything changed.

You choose which of these it sends:

Finding and change messages can be many a day across your tenants, so a new endpoint starts without them: tick them when you add it, or later on its page.

Add one

1. 1Get a web address that can receive the message. Automation tools give you one: in Power Automate, the trigger “When an HTTP request is received”; in Zapier or Make, a webhook trigger. It must start with https://.
2. 2In Settings → API and webhooks, add the address and tick the events you want.
3. 3Select Send test to check it arrives: it shows on the endpoint’s page with what your address answered. Pause it at any time without deleting it.

Each message is signed with a secret, so the receiving end can prove it came from ConfigCheckup. Automation tools usually do not need this; a developer building their own receiver should check it, as described in the API reference.

If a message does not arrive

If the address does not answer, or answers with an error, ConfigCheckup tries again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours: seven tries over about 21 hours. An answer that refuses the message outright, such as “not found” or a redirect to another address, is not tried again. Once 20 have failed in a row and the failures have gone on for a day, the endpoint is paused, nothing more is sent to it, and your Owners and Admins get an email; it is also on their Needs you list on Home until it is switched back on. A short outage, even during a burst of messages, does not pause it. Messages while it is paused this way are listed on its page as not sent, for 30 days, so they can be sent again once the address works.

Open the endpoint in Settings → API and webhooks to see every message of the last 30 days: when it was sent, what the address answered and how long it took. Select Send again beside any of them, or, once the address works again, Send them again for everything that did not arrive. A message sent again keeps its id, so a receiver that already has it can ignore it.

Replace the signing secret

On the endpoint’s page, choose how long the old secret keeps working, then Replace the secret. The new one is shown once. Until the old one stops, every message is signed with both, so your receiver keeps accepting messages while you put the new secret in. Choose Stop it at once if the old one may have leaked.

Streaming the audit log to your SIEM (beta)

If your security team watches Microsoft Sentinel or another SIEM, ConfigCheckup can send it the audit log as it happens: who signed in, approved, changed or exported what, at which tenant and from where. Alerts can go too, and the checks that start or stop failing at a tenant. It is included with Automate, and in beta: Sentinel is reached through the Azure Monitor Logs Ingestion API as Microsoft documents it, not tested against a live workspace.

1. 1In ConfigCheckup, go to Settings → Integrations and find SIEM stream. You need the Admin or Owner role.
2. 2For Microsoft Sentinel: register an app in your own Microsoft Entra tenant and give it a client secret. In the Log Analytics workspace Sentinel uses, add a custom log table (DCR-based) with the columns the page lists, and give the app the Monitoring Metrics Publisher role on its data collection rule. Then copy the logs ingestion endpoint, the rule’s immutable ID, the stream name and the app’s IDs and secret into the form.
3. 3For anything else: give the HTTPS address of your log collector (a syslog-over-HTTPS listener, Splunk HEC, a Logstash http input or similar), and the Authorization header it expects, if any. Records go as a JSON array, or one JSON object a line. A saved header is kept for the same host only: move the endpoint to another host and you type it again.
4. 4Select Send a test record, and look for it in your SIEM.

Records go every few minutes, in batches, each one once: ConfigCheckup remembers where it got to, and moves on only once a batch has arrived. If your SIEM cannot be reached, it tries again, a little later each time, and sends everything it missed once it can (the audit log and alerts however long it takes; findings opened or resolved if they are less than a month old); after two hours your Owners and Admins are told. If your plan stops including the stream, or the workspace is read-only, nothing is sent until that changes, and the page says so. Each record carries its own id, so the rare copy of a batch whose answer was lost on the way back can be told apart. The page shows the latest sends, what came back, and how many records are waiting.

In Sentinel, a record that is more than two days old when it arrives gets the time it arrived as its TimeGenerated: Log Analytics does that to any late record. That happens when you start with the last 7 or 30 days, or when the stream catches up after more than two days. Each record’s OccurredAt column always says when it happened, so query on OccurredAt when the time matters.

Power Automate

ConfigCheckup has a custom connector for Power Automate, Power Apps and Logic Apps, made from the API reference: each thing a key can do is an action in your flows, such as listing a tenant’s findings, queueing an assessment or drafting a change. It uses an API key: the actions that read are included on every plan, and those that queue assessments or draft changes with Automate.

1. 1In ConfigCheckup, create an API key for Power Automate in Settings → API and webhooks, with only the scopes your flows need.
2. 2In Power Automate, open Custom connectors, choose New custom connector → Import an OpenAPI from URL, name it ConfigCheckup and paste the address shown under Power Automate in Settings → API and webhooks. It ends in /api/v1/power-automate/apiDefinition.swagger.json. You can also download the file there and choose Import an OpenAPI file.
3. 3Check the details, then choose Create connector. The security, actions and fields are already filled in.
4. 4Make a connection. For the API key, type Bearer, a space, then the key: Bearer ccu_….
5. 5Use the actions in a flow, for example every Monday to list each tenant’s open critical findings and post them to a Teams channel.

To start a flow when something happens in ConfigCheckup, use a webhook: the trigger When an HTTP request is received gives you the address to add above. When we add to the API, import the connector again to see the new actions. If you use Microsoft’s paconn command-line tool, download the properties file beside the definition too.

Zapier and Make

There is no ConfigCheckup app in Zapier’s or Make’s directory. You do not need one: both work with webhooks and the API.

• When something happens: in Zapier, use Webhooks by Zapier → Catch Hook as the trigger (in Make, Webhooks → Custom webhook), and add the address it gives you as a webhook endpoint above. Each message’s fields are there to use in the next steps.
• To read or do something: use Webhooks by Zapier → Custom Request (in Make, HTTP → Make a request) with the address of the endpoint from the API reference, and a header named Authorization with the value Bearer ccu_….

Keeping them safe

• One key per tool, so revoking one does not break the others.
• Revoke a key straight away if it may have been shared or leaked, and when the tool that used it is retired.
• Limit a key to the tenants and IP addresses it needs. A leaked key that only works from your office, for two tenants, does far less harm.
• Check a key’s recent requests now and then. A burst of 404s or 403s can mean something is using it that should not.
• Keys stop working if your plan no longer includes the API, and start again if it does.
• Replace a webhook’s signing secret if it may have leaked, and stop the old one at once.
• Creating and revoking keys, changing their limits, exports through the API, adding, pausing and removing webhooks, replacing their secrets, sending messages again, and setting up, pausing or removing the SIEM stream are recorded in the audit log.