API keys and event webhooks

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 walks through creating a key, starting an article, following it to review and publishing it. Scopes and the person-only list are in authentication, and every endpoint is in the 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.

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.

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 and common errors.