flexkit webhooks

Manages the project’s outgoing 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

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.

flexkit webhooks ls [--json]

Examples

# 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.

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

Examples

# 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.

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

# 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.

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

# 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.

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

Examples

# 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.

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

Examples

# Delete a webhook
flexkit webhooks rm "Orders to ERP"
 
# Delete without a prompt
flexkit webhooks rm 3f9c2a1e-8d4b-4c7a-9e2f-5b6a7c8d9e0f --yes

Options

See also the 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.

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:

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