# Pscale Webhook > Manage PlanetScale database webhooks with the pscale CLI. Use when listing, inspecting, creating, updating, testing, or deleting webhooks, configuring event subscriptions, enabling or disabling delivery, or setting or clearing an Authorization header. Triggers on pscale webhook, database webhook, webhook authorization header, webhook events, webhook test. - Skill: `vince-winkintel/pscale-webhook` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds add vince-winkintel/pscale-webhook` - Raw SKILL.md: https://api.skillmd.com/api/skills/vince-winkintel/pscale-webhook/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: vince-winkintel (https://skillmd.com/u/vince-winkintel) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/vince-winkintel/pscale-webhook --- # pscale webhook Manage database webhooks and their event subscriptions. ## Inspect first ```bash set -o pipefail pscale webhook list --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 ```bash pscale webhook create \ --url https://hooks.example.com/planetscale \ --events branch.ready,deploy_request.opened \ --enabled=true \ --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: ```text 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](https://planetscale.com/docs/api/reference/create_webhook) for accepted names and the [webhook events reference](https://planetscale.com/docs/api/webhook-events) 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: ```bash pscale webhook create \ --url https://hooks.example.com/planetscale \ --authorization-header "$PLANETSCALE_WEBHOOK_AUTHORIZATION_HEADER" \ --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. ```bash # Save redacted pre-change state for rollback set -o pipefail pscale webhook list --org --format json | jq --arg id '' '.[] | select(.id == $id) | del(.secret)' # Disable or change subscriptions pscale webhook update \ --enabled=false \ --events branch.ready \ --org --format json | jq 'del(.secret)' # Remove the configured header explicitly pscale webhook update \ --clear-authorization-header \ --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=` 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. ```bash set -o pipefail pscale webhook list --org --format json | jq 'map(del(.secret))' pscale webhook test --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. ```bash set -o pipefail pscale webhook list --org --format json | jq 'map(del(.secret))' pscale webhook delete --org --format json pscale webhook list --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.