> ## Documentation Index > Fetch the complete documentation index at: https://planetscale.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # PlanetScale CLI commands: webhook Vitess, Neki, and Postgres ## Getting Started Make sure to first [set up your PlanetScale developer environment](https://planetscale.com/docs/cli/planetscale-environment-setup.md). 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](https://planetscale.com/docs/api/webhooks.md) for your database. **Usage:** ```bash theme={null} pscale webhook ``` ### Available sub-commands | **Sub-command** | **Description** | **Product** | | :- | :- | :- | | `create ` | Create a new webhook for a database | Vitess, Postgres, Neki | | `delete ` | Delete a webhook from a database | Vitess, Postgres, Neki | | `list ` | List all webhooks for a database | Vitess, Postgres, Neki | | `show ` | Show details for a specific webhook | Vitess, Postgres, Neki | | `test ` | Send a test event to a webhook | Vitess, Postgres, Neki | | `update ` | Update an existing webhook | Vitess, Postgres, Neki | #### Sub-command flags | **Sub-command flag** | **Description** | **Applicable sub-commands** | | :- | :- | :- | | `--authorization-header ` | Complete Authorization header value, including the authentication scheme (for example, `Bearer `). Sent unchanged. | `create`, `update` | | `--clear-authorization-header` | Remove the configured Authorization header. Cannot be used with `--authorization-header`. | `update` | | `--events ` | Comma-separated list of events to trigger the webhook. See [webhook events](https://planetscale.com/docs/api/webhook-events.md) for available events. | `create`, `update` | | `--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 ` | The organization for the current user | ### Global flags | **Command** | **Description** | | :- | :- | | `--api-token ` | The API token to use for authenticating against the PlanetScale API. | | `--api-url ` | The base URL for the PlanetScale API. Default is `https://api.planetscale.com/`. | | `--config ` | Config file. Default is `$HOME/.config/planetscale/pscale.yml`. | | `--debug` | Enable debug mode. | | `-f`, `--format ` | Show output in a specific format. Possible values: `human` (default), `json`, `csv`. | | `--no-color` | Disable color output. | | `--service-token ` | The service token for authenticating. | | `--service-token-id ` | The service token ID for authenticating. | ## Examples ### List webhooks for a database **Command:** ```bash theme={null} pscale webhook list --org ``` This lists all webhooks configured for the specified database. **Output:** ```bash theme={null} No webhooks exist in database . ``` Or if webhooks exist: ```bash theme={null} 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:** ```bash theme={null} pscale webhook create --org \ --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:** ```bash theme={null} ID URL SECRET EVENTS ENABLED CREATED AT UPDATED AT -------------- ------------------------------------- ------------------------------------------------------------------ ------------------------------- --------- ------------ ------------ abc123xyz https://example.com/webhook 8e46bd50ca092655b1efdfca329f0d79eb976714030a8bfa031397eb0d1cb433 branch.ready, branch.sleeping No now now ``` > [!NOTE] > > 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](https://planetscale.com/docs/api/webhooks.md#validating-a-webhook-signature). You can also view the secret later from the database settings page in the dashboard. ### Show webhook details **Command:** ```bash theme={null} pscale webhook show --org ``` This displays detailed information about a specific webhook, including its ID, URL, secret, events, enabled status, and timestamps. **Output:** ```bash theme={null} 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 ``` > [!NOTE] > > 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](https://planetscale.com/docs/api/webhooks.md#validating-a-webhook-signature). ### Update a webhook **Command:** ```bash theme={null} pscale webhook update --org --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: ```bash theme={null} pscale webhook update --org \ --clear-authorization-header ``` **Output:** ```bash theme={null} 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:** ```bash theme={null} pscale webhook test --org ``` 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:** ```bash theme={null} Test event was successfully sent to webhook . ``` ### Delete a webhook **Command:** ```bash theme={null} pscale webhook delete --org ``` This permanently deletes the webhook from the database. **Output:** ```bash theme={null} Webhook was successfully deleted from . ``` ## Need help? Get help from [the PlanetScale Support team](https://planetscale.com/contact?initial=support), or join our [Discord community](https://pscale.link/community) to see how others are using PlanetScale. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.