PlanetScale CLI commands: webhook

Getting Started

Make sure to first set up your PlanetScale developer environment. Once you’ve installed the pscale CLI, you can interact with PlanetScale and manage your databases straight from the command line.

The `webhook` command

This command allows you to create, list, update, test, and delete webhooks for your database. Usage:

pscale webhook <SUB-COMMAND> <FLAG>

Available sub-commands

Sub-command	Description	Product
`create <DATABASE_NAME>`	Create a new webhook for a database	Vitess, Postgres, Neki
`delete <DATABASE_NAME> <WEBHOOK_ID>`	Delete a webhook from a database	Vitess, Postgres, Neki
`list <DATABASE_NAME>`	List all webhooks for a database	Vitess, Postgres, Neki
`show <DATABASE_NAME> <WEBHOOK_ID>`	Show details for a specific webhook	Vitess, Postgres, Neki
`test <DATABASE_NAME> <WEBHOOK_ID>`	Send a test event to a webhook	Vitess, Postgres, Neki
`update <DATABASE_NAME> <WEBHOOK_ID>`	Update an existing webhook	Vitess, Postgres, Neki

Sub-command flags

Sub-command flag	Description	Applicable sub-commands
`--authorization-header <VALUE>`	Complete Authorization header value, including the authentication scheme (for example, `Bearer <token>`). Sent unchanged.	`create`, `update`
`--clear-authorization-header`	Remove the configured Authorization header. Cannot be used with `--authorization-header`.	`update`
`--events <EVENTS>`	Comma-separated list of events to trigger the webhook. See webhook events for available events.	`create`, `update`
`--url <URL>`	The HTTPS URL where webhook events will be sent	`create`, `update`
`--enabled`	Enable or disable the webhook. Use `--enabled` or `--enabled=true` to enable, `--enabled=false` to disable. Webhooks are disabled by default when created.	`update`

Available flags

Flag	Description
`-h`, `--help`	View help for `webhook` command
`--org <ORGANIZATION_NAME>`	The organization for the current user

Global flags

Command	Description
`--api-token <TOKEN>`	The API token to use for authenticating against the PlanetScale API.
`--api-url <URL>`	The base URL for the PlanetScale API. Default is `https://api.planetscale.com/`.
`--config <CONFIG_FILE>`	Config file. Default is `$HOME/.config/planetscale/pscale.yml`.
`--debug`	Enable debug mode.
`-f`, `--format <FORMAT>`	Show output in a specific format. Possible values: `human` (default), `json`, `csv`.
`--no-color`	Disable color output.
`--service-token <TOKEN>`	The service token for authenticating.
`--service-token-id <TOKEN_ID>`	The service token ID for authenticating.

Examples

List webhooks for a database

Command:

pscale webhook list <DATABASE_NAME> --org <ORGANIZATION_NAME>

This lists all webhooks configured for the specified database. Output:

No webhooks exist in database <DATABASE_NAME>.

Or if webhooks exist:

  ID             URL                                   EVENTS                          ENABLED   CREATED AT   UPDATED AT
 -------------- ------------------------------------- ------------------------------- --------- ------------ ------------
  abc123xyz      https://example.com/webhook           branch.ready, branch.sleeping   Yes       2 days ago   1 day ago

Create a webhook

Command:

pscale webhook create <DATABASE_NAME> --org <ORGANIZATION_NAME> \
  --events "branch.ready,branch.sleeping" \
  --url https://example.com/webhook \
  --authorization-header "Bearer $AUTOMATION_TOKEN"

This creates a new webhook for the specified database with the selected events. The example sends the complete Authorization header value, Bearer $AUTOMATION_TOKEN, with the token supplied by the environment variable. PlanetScale sends the value unchanged. The header value is write-only and will not appear in command output. The webhook will be disabled by default until you enable it with the update command. Output:

  ID             URL                                   SECRET                                                             EVENTS                          ENABLED   CREATED AT   UPDATED AT
 -------------- ------------------------------------- ------------------------------------------------------------------ ------------------------------- --------- ------------ ------------
  abc123xyz      https://example.com/webhook           8e46bd50ca092655b1efdfca329f0d79eb976714030a8bfa031397eb0d1cb433   branch.ready, branch.sleeping   No        now          now

When you create a webhook, a secret is generated and displayed only once in the output. Store this secret securely as you’ll need it to validate webhook signatures. You can also view the secret later from the database settings page in the dashboard.

Show webhook details

Command:

pscale webhook show <DATABASE_NAME> <WEBHOOK_ID> --org <ORGANIZATION_NAME>

This displays detailed information about a specific webhook, including its ID, URL, secret, events, enabled status, and timestamps. Output:

  ID             URL                                   SECRET                                                             EVENTS                          ENABLED   CREATED AT       UPDATED AT
 -------------- ------------------------------------- ------------------------------------------------------------------ ------------------------------- --------- ---------------- ----------------
  abc123xyz      https://example.com/webhook           b4c29e6ae54a6456496cec7dcbfad7ace6e973a694802de2978b4d6e001fca6e   branch.ready, branch.sleeping   No        25 seconds ago   25 seconds ago

The show command displays the webhook secret, which is useful if you need to retrieve it after creation. Store this secret securely as you’ll need it to validate webhook signatures.

Update a webhook

Command:

pscale webhook update <DATABASE_NAME> <WEBHOOK_ID> --org <ORGANIZATION_NAME> --enabled

This enables an existing webhook. To disable a webhook, use --enabled=false. You can also update the events or URL, or set an Authorization header with --authorization-header. Supply the complete header value, including the authentication scheme—for example, --authorization-header "Bearer $AUTOMATION_TOKEN". PlanetScale sends the value unchanged. Omitting --authorization-header preserves the configured value. Webhook output indicates whether an Authorization header is configured without revealing its value. To remove a configured header, run:

pscale webhook update <DATABASE_NAME> <WEBHOOK_ID> --org <ORGANIZATION_NAME> \
  --clear-authorization-header

Output:

  ID             URL                                   EVENTS                          ENABLED   CREATED AT     UPDATED AT
 -------------- ------------------------------------- ------------------------------- --------- -------------- ------------
  abc123xyz      https://example.com/webhook           branch.ready, branch.sleeping   Yes       58 seconds ago now

Test a webhook

Command:

pscale webhook test <DATABASE_NAME> <WEBHOOK_ID> --org <ORGANIZATION_NAME>

This sends a test event to the webhook URL to verify it’s configured correctly. You can only send one test event every 20 seconds per webhook. Output:

Test event was successfully sent to webhook <WEBHOOK_ID>.

Delete a webhook

Command:

pscale webhook delete <DATABASE_NAME> <WEBHOOK_ID> --org <ORGANIZATION_NAME>

This permanently deletes the webhook from the database. Output:

Webhook <WEBHOOK_ID> was successfully deleted from <DATABASE_NAME>.

Need help?

Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.

Introduction

Using the pscale CLI

CLI command reference

PlanetScale CLI commands: webhook

Getting Started

The `webhook` command

Available sub-commands

Sub-command flags

Available flags

Global flags

Examples

List webhooks for a database

Create a webhook

Show webhook details

Update a webhook

Test a webhook

Delete a webhook

Need help?

​Getting Started

​The webhook command

​Available sub-commands

​Sub-command flags

​Available flags

​Global flags

​Examples

​List webhooks for a database

​Create a webhook

​Show webhook details

​Update a webhook

​Test a webhook

​Delete a webhook

​Need help?

Getting Started

The `webhook` command

Available sub-commands

Sub-command flags

Available flags

Global flags

Examples

List webhooks for a database

Create a webhook

Show webhook details

Update a webhook

Test a webhook

Delete a webhook

Need help?