Pscale Webhook

pscale webhook

Manage database webhooks and their event subscriptions.

Inspect first

set -o pipefail
pscale webhook list <database> --org <org> --format json |
  jq 'map(del(.secret))'

Use the redacted list for routine identifiers and persisted state. Webhook resource JSON from create, show, list, or update can contain the signing secret because the CLI serializes the raw API model. Do not capture it unredacted in logs, chat, or agent context; only an intentional create/show flow that writes directly to an approved secret store should retain it. pscale webhook show deliberately returns the secret, and human output has a secret column. When an exact show is unavoidable for non-secret inspection, pipe JSON directly through jq 'del(.secret)' before capturing output. authorization_header_configured reveals only whether the separate Authorization header is configured, never its value.

Create

pscale webhook create <database> \
  --url https://hooks.example.com/planetscale \
  --events branch.ready,deploy_request.opened \
  --enabled=true \
  --org <org> --format json

--url is required. Confirm the destination host, TLS endpoint, subscribed events, enabled state, and receiver ownership before creation. Successful create output includes the generated webhook signing secret in both human and JSON formats. Capture it from that response directly into an approved secret manager; do not print it into logs, paste it into tickets, or commit it. Treat the create response as the one reliable capture point.

--events accepts a comma-separated list. Published event names are:

branch.anomaly
branch.out_of_memory
branch.primary_promoted
branch.ready
branch.schema_recommendation
branch.sleeping
branch.start_maintenance
backup.failed
backup.succeeded
cluster.storage
database.access_request
deploy_request.closed
deploy_request.errored
deploy_request.in_progress
deploy_request.opened
deploy_request.pending_cutover
deploy_request.queued
deploy_request.reverted
deploy_request.schema_applied
keyspace.storage
webhook.test

The CLI forwards event strings to the PlanetScale API without client-side validation. Use the events enum in the webhook API reference for accepted names and the webhook events reference for trigger and payload details; the general events page can lag the API enum. An unknown or unsupported name is not normalized by the CLI and can fail at the API.

Authorization header

--authorization-header accepts the complete HTTP Authorization value, such as Bearer …. It is a secret-bearing argument. Do not place a literal credential in documentation, shell history, logs, chat, source control, or process captures. Use an approved secret source and preserve only the variable reference in reusable command text:

pscale webhook create <database> \
  --url https://hooks.example.com/planetscale \
  --authorization-header "$PLANETSCALE_WEBHOOK_AUTHORIZATION_HEADER" \
  --org <org> --format json

Do not run this form until the environment variable is populated outside the agent-visible context. Verify only authorization_header_configured: true; never attempt to read the value back.

Update

Pass at least one of --url, --authorization-header, --clear-authorization-header, --events, or --enabled. Only supplied fields change, but --events replaces the entire subscription list rather than appending to it. Read the current list and include every event that should remain subscribed.

# Save redacted pre-change state for rollback
set -o pipefail
pscale webhook list <database> --org <org> --format json |
  jq --arg id '<webhook-id>' '.[] | select(.id == $id) | del(.secret)'

# Disable or change subscriptions
pscale webhook update <database> <webhook-id> \
  --enabled=false \
  --events branch.ready \
  --org <org> --format json | jq 'del(.secret)'

# Remove the configured header explicitly
pscale webhook update <database> <webhook-id> \
  --clear-authorization-header \
  --org <org> --format json | jq 'del(.secret)'

# Each synchronous update response is the read-back for that change

Before updating, save the redacted non-secret configuration (url, events, and enabled) and ensure the current Authorization value is available separately if rollback may need to restore it—the API does not return that header value. To roll back, re-run webhook update with the previous --url, complete --events list, and explicit --enabled=<true|false> values, plus either the prior --authorization-header value or --clear-authorization-header. The synchronous update response verifies persisted non-secret state; use webhook test to verify receiver behavior.

--authorization-header and --clear-authorization-header are mutually exclusive. An empty --authorization-header value is rejected; use the clear flag. Changing or clearing authentication can interrupt deliveries, so coordinate the receiver update and verify authorization_header_configured afterward.

Test and delete

webhook test sends a real event to the external receiver. Confirm the destination and downstream side effects before running it. A successful CLI response proves dispatch was accepted, not that the receiver processed it; verify receiver-side evidence when available.

set -o pipefail
pscale webhook list <database> --org <org> --format json |
  jq 'map(del(.secret))'
pscale webhook test <database> <webhook-id> --org <org> --format json

Deletion has no CLI confirmation flag. Treat it as destructive: inspect the exact webhook, inventory dependencies, obtain explicit approval, delete, and read back the list.

set -o pipefail
pscale webhook list <database> --org <org> --format json |
  jq 'map(del(.secret))'
pscale webhook delete <database> <webhook-id> --org <org> --format json
pscale webhook list <database> --org <org> --format json |
  jq 'map(del(.secret))'

When scripting against --format json, probe one representative response first and handle optional fields defensively. The CLI serializes the underlying API webhook model for JSON, while human and CSV output use a smaller normalized view, so fields can differ and the JSON model can gain fields as the API evolves. Do not build strict decoders from the command-reference snippets or assume table and JSON output have identical fields.

Reference

See references/commands.md for checksum-verified command help surfaces.