---
title: 'flexkit webhooks'
description: 'List, create, change, pause and delete outgoing webhooks from the terminal or a CI pipeline.'
---

# `flexkit webhooks`

Manages the project's [outgoing webhooks](/docs/api/webhooks): HTTP calls Flexkit makes to your URL when records are created, updated or deleted. Use it to set up a receiver from a script, rotate the receiver's credentials, or pause a webhook while the receiver is down.

## Synopsis

```bash
flexkit webhooks <subcommand> [arguments] [options]
```

Running `flexkit webhooks` without a subcommand runs `flexkit webhooks ls`. Wherever a command takes `<idOrName>`, you can pass the webhook id or its exact name (case-insensitive).

## `webhooks ls`

List the webhooks with their status, request, events, entities, number of deliveries and last call. Alias: `list`.

```bash
flexkit webhooks ls [--json]
```

### Examples

```bash
# List webhooks
flexkit webhooks ls

# Names of the disabled webhooks
flexkit webhooks ls --json | jq -r '.webhooks[] | select(.enabled | not) | .name'
```

## `webhooks inspect`

Show one webhook: receiver, events, entities, headers, secret and delivery counts. Header values and the secret are masked unless you pass `--show-secrets`, in `--json` output too, where they read `[redacted]`. Alias: `get`.

```bash
flexkit webhooks inspect <idOrName> [--show-secrets] [--json]
```

### Examples

```bash
# Show a webhook by name
flexkit webhooks inspect "Orders to ERP"

# Include header values and the secret
flexkit webhooks inspect 3f9c2a1e-8d4b-4c7a-9e2f-5b6a7c8d9e0f --show-secrets

# Delivery counts as JSON
flexkit webhooks inspect "Orders to ERP" --json | jq '.webhook.deliveries'
```

## `webhooks create`

Create a webhook. Only `--url` is required: by default the webhook fires on every event (`create`, `update`, `delete`) of every entity, sends a `POST` with the JSON payload, is enabled, and is named after the URL host. Alias: `add`.

```bash
flexkit webhooks create --url <url> [--name <name>] [--description <text>] [--entity <name>]... [--on <event>]... [--header <Key=Value>]... [--method <method>] [--secret <secret>] [--disabled] [--json]
```

Entity names must exist in the deployed schema (for example `Order`, not `order`). The number of webhooks per project depends on your plan.

### Examples

```bash
# Notify a receiver about new and changed orders
flexkit webhooks create --name "Orders to ERP" --url https://erp.example.com/hooks/flexkit \
  --entity Order --on create --on update

# Authenticate to the receiver with a header
flexkit webhooks create --url https://hooks.example.com/flexkit \
  --header "Authorization=Bearer $RECEIVER_TOKEN"

# Create it disabled and keep its id
WEBHOOK_ID=$(flexkit webhooks create --url https://staging.example.com/hook --disabled --json | jq -r '.webhook.id')
```

## `webhooks update`

Change a webhook. Options you do not pass keep their value. `--entity` and `--on` replace the current lists; `--all-entities` removes the entity filter. `--header Key=Value` adds a header or replaces the one with the same name (case-insensitive) and keeps the others; `--header Key=` or `--remove-header Key` stops sending it. `--secret ""` clears the secret. Alias: `edit`. `--entity`, `--all-entities` and `--on` edit a webhook with one trigger; a webhook with several triggers (set in the dashboard or with `triggers` in the API) refuses them.

```bash
flexkit webhooks update <idOrName> [--url <url>] [--name <name>] [--description <text>] [--entity <name>]... [--all-entities] [--on <event>]... [--header <Key=Value>]... [--remove-header <Key>]... [--method <method>] [--secret <secret>] [--json]
```

### Examples

```bash
# Point a webhook at a new URL
flexkit webhooks update "Orders to ERP" --url https://erp.example.com/v2/hooks/flexkit

# Rotate the receiver token
flexkit webhooks update "Orders to ERP" --header "Authorization=Bearer $NEW_RECEIVER_TOKEN"

# Fire only on deletes, of every entity
flexkit webhooks update 3f9c2a1e-8d4b-4c7a-9e2f-5b6a7c8d9e0f --on delete --all-entities
```

## `webhooks enable` and `webhooks disable`

Turn one or more webhooks on or off. A disabled webhook keeps its settings; changes made while it is off are not delivered later.

```bash
flexkit webhooks enable <idOrName>... [--json]
flexkit webhooks disable <idOrName>... [--json]
```

### Examples

```bash
# Pause a webhook during receiver maintenance, then resume it
flexkit webhooks disable "Orders to ERP"
flexkit webhooks enable "Orders to ERP"
```

## `webhooks rm`

Delete one or more webhooks. Every name or id is looked up first, so a typo deletes nothing. The command asks for confirmation; pass `--yes` in scripts. Aliases: `remove`, `delete`.

```bash
flexkit webhooks rm <idOrName>... [--yes] [--json]
```

### Examples

```bash
# Delete a webhook
flexkit webhooks rm "Orders to ERP"

# Delete without a prompt
flexkit webhooks rm 3f9c2a1e-8d4b-4c7a-9e2f-5b6a7c8d9e0f --yes
```

## Options

| Option                  | Subcommands        | Description                                                                         |
| ----------------------- | ------------------ | ----------------------------------------------------------------------------------- |
| `--url <url>`           | `create`, `update` | The `http://` or `https://` address that receives the events. Required for create.  |
| `--name <name>`         | `create`, `update` | Webhook name. Default: the URL host.                                                |
| `--description <text>`  | `create`, `update` | What the webhook is for.                                                            |
| `--entity <name>`       | `create`, `update` | Only changes to this entity. Repeatable or comma separated. Default: every entity.  |
| `--all-entities`        | `update`           | Remove the entity filter.                                                           |
| `--on <event>`          | `create`, `update` | `create`, `update`, `delete` or `all`. Repeatable or comma separated. Default: all. |
| `--header <Key=Value>`  | `create`, `update` | Header sent with every delivery. Repeatable. `Key=` removes it on update.           |
| `--remove-header <Key>` | `update`           | Stop sending a header. Repeatable.                                                  |
| `--method <method>`     | `create`, `update` | `POST` (default), `PUT`, `PATCH`, `GET` or `DELETE`. `GET` sends no body.           |
| `--secret <secret>`     | `create`, `update` | A shared secret stored with the webhook. `""` clears it.                            |
| `--disabled`            | `create`           | Create the webhook turned off.                                                      |
| `--show-secrets`        | `inspect`          | Print header values and the secret.                                                 |
| `--yes`, `-y`           | `rm`               | Skip the confirmation prompt.                                                       |
| `--json`                | all                | Print JSON on stdout.                                                               |
| `--project <ID>`, `-p`  | all                | Project to use. Default: the [linked](/docs/cli/link) project.                      |

See also the [global options](/docs/cli/global-options).

## Permissions

- Listing and inspecting webhooks needs the **Owner**, **Developer** or **Viewer** role.
- Creating, changing, enabling, disabling and deleting webhooks needs the **Owner** or **Developer** role.
- Header values and the secret are returned only to owners, and to developers who belong to every space of the project. Others see the header names and whether a secret is set, even with `--show-secrets`.
- Commands work with a `flexkit login` session and with project API tokens, with the token's own role. Changes made with a token are attributed to the member who created it.
- A webhook receives the changes of every space, so `create` and `update` need every space of the project, for signed-in members and tokens alike: owners always have it; a developer must belong to every space, and a token must hold every space (an owner-created token given all spaces, or any token in a project without spaces). Without it, the commands answer `A webhook receives changes from every space; you need to belong to every space of the project, or ask an owner.` A developer or token limited to some spaces can still list, inspect and delete webhooks.

## Notes

- Header values usually hold the receiver's credentials. Pass them from environment variables or your CI secret store, not literally on the command line, so they stay out of shell history and logs.
- Flexkit does not sign deliveries with the secret yet. Authenticate deliveries with a header such as `Authorization` over HTTPS; see [receiver authentication](/docs/api/webhooks#receiver-authentication).

## Configure webhooks in CI

Create a project API token with the **Developer** role and every space of the project, and store it as a CI secret. This GitHub Actions job makes sure the ERP webhook exists and points at the current receiver on every deploy:

```yaml filename=".github/workflows/webhooks.yml"
name: Configure webhooks
on:
  push:
    branches: [main]

jobs:
  webhooks:
    runs-on: ubuntu-latest
    env:
      FLEXKIT_TOKEN: ${{ secrets.FLEXKIT_TOKEN }}
      FLEXKIT_PROJECT_ID: ${{ vars.FLEXKIT_PROJECT_ID }}
      RECEIVER_TOKEN: ${{ secrets.ERP_RECEIVER_TOKEN }}
    steps:
      - run: npm install -g @flexkit/cli
      - name: Create or update the ERP webhook
        run: |
          if flexkit webhooks inspect "Orders to ERP" --json > /dev/null 2>&1; then
            flexkit webhooks update "Orders to ERP" \
              --url https://erp.example.com/hooks/flexkit \
              --header "Authorization=Bearer $RECEIVER_TOKEN"
          else
            flexkit webhooks create --name "Orders to ERP" \
              --url https://erp.example.com/hooks/flexkit --entity Order --on create --on update \
              --header "Authorization=Bearer $RECEIVER_TOKEN"
          fi
```


---

[View full sitemap](/docs/sitemap.md)