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.
Docs pagesSecrets and sender verification
On this pageSecrets
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.
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.
spec:
source:
preset: githubProviders
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 guideStripe
stripe
Stripe-Signature (t=…, v1=…) with a 5 minute tolerance.
Setup guideGitHub
github
X-Hub-Signature-256 (sha256=…) against the secret set on the webhook.
Setup guideMeta (Facebook, Instagram, Messenger)
meta
X-Hub-Signature-256 signed with the App Secret, plus the GET hub.challenge handshake.
Setup guideWhatsApp Cloud API
whatsapp
Meta signature and handshake. Delivery receipts are skipped.
Setup guideShopify
shopify
X-Shopify-Hmac-Sha256 (base64 HMAC of the body).
Setup guideTwilio
twilio
X-Twilio-Signature over the URL and sorted form params. Form bodies are parsed into fields.
Setup guideResend
resend
Svix-signed (svix-id, svix-timestamp, svix-signature).
Setup guide
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