# API keys and event webhooks

> Owners create workspace API keys for scripts and CI, with scopes for what each may do, and add signed event webhooks so other systems hear about changes.

Source: https://wavefront.adwave.com/help/agents-and-api/api-keys-and-webhooks (updated 2026-10-14)

An API key lets a script, CI job or automation use one workspace through the REST API. Event webhooks do the reverse: Wavefront sends a signed request to your address when something happens, such as a draft ready for review. Owners manage both in **Settings**.

## Create an API key

1. Open **Settings → API and MCP**.
2. Under **Create a key**, give it a **Name** that says what uses it.
3. Pick its **Scopes**: only what the job needs.
4. Choose **Create key**. Copy it now with **Copy**; it won't be shown again.

Store the key as a secret, never in a committed file. Wavefront keeps only a hash of it.

| Scope | Allows |
| --- | --- |
| `generations:read` | Read generations, versions, strategies, the calendar, schedules, publications, search data and suggestions |
| `generations:write` | Create and revise drafts, answer questions, comment, plan with the strategist, manage the backlog and decide on suggestions |
| `publish` | Publish and schedule approved versions |
| `context:read` | Read the workspace documents |
| `context:write` | Update the workspace documents |
| `webhooks` | Event webhooks (subscribing also needs `generations:read`) |
| `autopilot` | Set autopilot's cadence and backlog settings |
| `destinations` | Add, edit and test destinations, including their credentials. Owners are emailed |
| `integrations` | Read, change and test Slack and Microsoft Teams settings |

## What a key can't do

A key acts for the workspace, not a person, so it never gets the person-only actions: approving a version, withdrawing a page, posting to social networks, sending newsletters, turning auto-approve on, team and billing changes, or connecting accounts with a sign-in.

## Revoke a key

Choose **Revoke** next to the key. Anything using it stops working at once. A key is also revoked when the owner who created it is demoted or removed, and the list marks keys whose creator is no longer an owner.

## Use the key

Send it as a bearer token on every request to the REST API. The [quickstart](/docs/quickstart) walks through creating a key, starting an article, following it to review and publishing it. Scopes and the person-only list are in [authentication](/docs/authentication), and every endpoint is in the [API reference](/docs/api/reference). The API needs the trial or the plan.

## Add an event webhook

1. Open **Settings → Integrations** and find **Event webhooks**.
2. Choose **Add webhook**, enter your https address and pick the events to send.
3. Copy the signing secret. It's shown once.
4. Choose **Send test** to check your endpoint answers.

Events include a draft ready for review, a draft that needs input, a version approved, changes requested, a post published or withdrawn, a publish that failed, a new comment, a plan saved, and new suggestions. Payloads carry ids, titles and links, never full article bodies. Read the rest through the API.

## Manage webhooks

Each webhook has **Pause** (or **Turn on**), **Rotate secret**, **Delete** and a delivery log kept for 30 days, with **Redeliver** for any delivery. A workspace can have up to 20 webhooks.

- **Signatures.** Every request is signed following Standard Webhooks. Verify the signature against the raw body before trusting it. After **Rotate secret**, both secrets sign requests for 24 hours.
- **Retries.** Answer with any 2xx within 15 seconds. Anything else is tried again, up to 8 attempts in all over about 24 hours. A `410 Gone` answer turns the webhook off at once.
- **Failures.** A webhook whose deliveries keep failing for 24 hours is turned off, and the owner who added it gets an email. Turn it back on when your endpoint is fixed.
- **Duplicates.** Delivery is at least once and can arrive out of order. Use the event id to skip repeats.

Code samples for verifying signatures are in the [webhooks guide](/docs/webhooks).

## Event webhooks and webhook destinations

These are different. An event webhook tells you that something happened. A webhook destination, added under **Settings → Publishing**, receives the published article itself when you publish to it. See [connect a destination](/help/publishing/connect-a-destination).

## If something goes wrong

- **`401`.** The key is missing, mistyped or revoked.
- **`403 forbidden` naming a scope.** The key lacks that scope. Create a new key with it.
- **`402 plan_required`.** The trial ended without a plan. An owner chooses a plan.
- **`403 human_approval_required`.** Only a person can approve, in the web app.

The full list is in [errors](/docs/errors) and [common errors](/help/troubleshooting/common-errors).

---

Wavefront by Adwave. https://wavefront.adwave.com/