Skip to content

Secrets and sender verification

Every hook declares how to check that a request really came from the sender. Store the signing secret in your workspace, then name a preset or write the verification block yourself.

Secrets

Hooks name a secret as ${NAME} and never hold its value. Workspace secrets are encrypted at rest and write-only: no command or route returns a value.

  • secrets set NAME reads the value from a hidden prompt, or from stdin. Names are UPPER_SNAKE_CASE. Piping keeps the value out of your shell history.
  • secrets list shows each name and when it last changed. --json adds when each one was created, for scripts.
  • secrets delete NAME is for workspace owners only. It asks for confirmation on a terminal, and hooks that reference the name break until it is set again.

Any member can set a secret. Only owners can delete one.

terminal
printf %s "$STRIPE_WEBHOOK_SECRET" | hooksmith secrets set STRIPE_WEBHOOK_SECRET
hooksmith secrets set SLACK_WEBHOOK            # hidden prompt on a terminal
hooksmith secrets list
hooksmith secrets delete OLD_TOKEN --yes      # owners only

Verify the sender

Every hook declares how to check that a request really came from the sender. A preset sets the signature scheme for that provider, so you only name the provider. The providers below lists what each one checks. A sender without a preset gets an explicit source.verification block, and any field you write yourself wins over the preset's default.

Signing secrets are workspace secrets, encrypted at rest. The hook refers to them as ${NAME}; the value never goes into the YAML.

hook.yaml
spec:
  source:
    preset: github

Providers

Eight presets ship with the CLI. Each one sets the verification scheme, the event source type and a starter transform. Scaffold one with --preset, then run hooksmith presets <id> for the exact secret names and the steps to point the provider at your URL.

  • Standard Webhooks / Svix

    standard-webhooks

    webhook-id, webhook-timestamp and webhook-signature, with a 5 minute tolerance. svix-* headers also work.

    Setup guide
  • Stripe

    stripe

    Stripe-Signature (t=…, v1=…) with a 5 minute tolerance.

    Setup guide
  • GitHub

    github

    X-Hub-Signature-256 (sha256=…) against the secret set on the webhook.

    Setup guide
  • Meta (Facebook, Instagram, Messenger)

    meta

    X-Hub-Signature-256 signed with the App Secret, plus the GET hub.challenge handshake.

    Setup guide
  • WhatsApp Cloud API

    whatsapp

    Meta signature and handshake. Delivery receipts are skipped.

    Setup guide
  • Shopify

    shopify

    X-Shopify-Hmac-Sha256 (base64 HMAC of the body).

    Setup guide
  • Twilio

    twilio

    X-Twilio-Signature over the URL and sorted form params. Form bodies are parsed into fields.

    Setup guide
  • Resend

    resend

    Svix-signed (svix-id, svix-timestamp, svix-signature).

    Setup guide
terminal
hooksmith presets stripe              # secrets and setup steps
hooksmith new my-stripe --preset stripe

# The GitHub preset, as shipped in hooks/examples/github.yaml:
apiVersion: hooksmith/v1
kind: Hook
metadata:
  name: github
  description: GitHub → destination
spec:
  source:
    preset: github
  destinations:
    - name: primary
      url: ${DESTINATION_URL}
      method: POST
      timeout: 8s
      retries:
        max: 3
        backoff: exponential
        initialDelay: 500ms
  transform:
    engine: handlebars
    fields:
      title: "{{repository.full_name}}{{#if action}} · {{action}}{{/if}}"
      message: '{{#if pull_request}}PR #{{pull_request.number}} {{pull_request.title}}{{else if head_commit}}{{pusher.name}} pushed: {{firstLine head_commit.message}}{{else if issue}}Issue #{{issue.number}} {{issue.title}}{{else}}{{default zen "event"}}{{/if}}'
      open_url: "{{default pull_request.html_url (default issue.html_url repository.html_url)}}"
      interruption_level: active
  conditions:
    - if: sender.type == "Bot"
      then:
        skip: true
  variables:
    - name: GITHUB_WEBHOOK_SECRET
      from: secret
    - name: DESTINATION_URL
      from: secret