Skip to content

Provider guide

Standard Webhooks with Hooksmith

To verify a Standard Webhooks request, sign webhook-id, webhook-timestamp and the raw body joined by dots with HMAC-SHA256, using your base64 whsec_ secret, and compare the result with the v1 entries in webhook-signature. Hooksmith does this for any sender that follows the spec or uses Svix, and rejects timestamps more than 5 minutes off.

How Standard Webhooks signs webhooks

The standard-webhooks verification type implements the symmetric v1 scheme from the Standard Webhooks 1.0 specification.

Headers
webhook-id, webhook-timestamp and webhook-signature. A request with svix-id, svix-timestamp and svix-signature instead is accepted too.
Algorithm
HMAC-SHA256, base64 encoded, compared in constant time.
What is signed
<id>.<timestamp>.<raw body>.
Key
The whsec_ secret with the prefix removed and the rest base64 decoded.
Signature header
A space separated list of v1,<base64> entries. Any matching entry passes, which allows secret rotation.
Replay window
The timestamp must be within 5 minutes of the server clock. Change it with source.verification.tolerance.
  • Only v1 symmetric signatures are supported. Asymmetric v1a signatures in the same header are ignored.
  • A second request with the same webhook-id (or svix-id) within 24 hours is reported as a duplicate and is not delivered again.
  • A failed check answers 401 VERIFICATION_FAILED and stores nothing.

Set it up

Hooksmith turns the provider preset into a hook you own. The provider creates the signing secret when you add the endpoint, so deploy first, add the URL in the provider dashboard, then store the secret it shows you. Secrets live in your workspace vault and never go in the YAML. Store WEBHOOK_SIGNING_SECRET, DESTINATION_URL.

  1. In the sender's dashboard, add an endpoint and paste the /h/<id> URL that hooksmith deploy printed.
  2. Copy the endpoint's signing secret (it starts with whsec_) and store it with hooksmith secrets set WEBHOOK_SIGNING_SECRET.
terminal
hooksmith login
hooksmith new standard-events --preset standard-webhooks --yes
# paste the example hook into .hooksmith/hooks/standard-events.yaml
hooksmith secrets set DESTINATION_URL
hooksmith test standard-events --payload ./contact.json
hooksmith deploy standard-events   # prints the /h/<id> URL
# add the URL in the provider dashboard, copy its signing secret, then:
hooksmith secrets set WEBHOOK_SIGNING_SECRET

hooksmith new writes the preset's starter hook. Replace its contents with the example below, or edit it by hand. The CLI's built-in test sample is generic, so pass your own payload with --payload; a matching one is in the next section. The command reference is in the docs.

Forward contact events from any compliant sender

The Standard Webhooks payload recommendation has a type, a timestamp and a data object. This hook forwards only contact.created and contact.updated, and flattens the data you need.

.hooksmith/hooks/standard-events.yaml
apiVersion: hooksmith/v1
kind: Hook
metadata:
  name: standard-events
  description: Contact events to the CRM sync service
spec:
  source:
    preset: standard-webhooks
  destinations:
    - name: crm-sync
      url: ${DESTINATION_URL}
      method: POST
      timeout: 8s
      retries:
        max: 5
        backoff: exponential
        initialDelay: 1s
  transform:
    engine: handlebars
    fields:
      event: "{{{type}}}"
      occurred_at: "{{{timestamp}}}"
      contact_id: "{{{data.id}}}"
      name: "{{{data.name}}}"
  conditions:
    - if: type != "contact.created" && type != "contact.updated"
      then:
        skip: true
  variables:
    - name: WEBHOOK_SIGNING_SECRET
      from: secret
    - name: DESTINATION_URL
      from: secret
contact.json
{
  "type": "contact.created",
  "timestamp": "2026-10-09T12:00:00.000Z",
  "data": { "id": "ct_1", "name": "Ada" }
}
  • DESTINATION_URL is a workspace secret, so the URL stays out of the YAML. Store it with hooksmith secrets set DESTINATION_URL.
  • Values use triple braces so quotes, ampersands, apostrophes and equals signs reach your endpoint as typed. With double braces, template output is HTML-escaped.
  • The spec does not fix the payload shape, so adjust the field names to what your sender actually sends.

Event types in Standard Webhooks

The specification leaves event names to the sender. It recommends a dot-separated type such as user.created or invoice.paid, a timestamp of when the event occurred, and the event data under data.

type
Full-stop delimited event type, such as contact.created.
timestamp
When the event happened, in ISO 8601. It can differ from webhook-timestamp, which is the time of the delivery attempt.
data
The event data.

Test against localhost

The Hooksmith desktop app for Mac can tunnel stored events to a server on your machine. In raw mode it replays the original body bytes and the stored provider headers. Proxy headers such as x-forwarded-host are never stored, so they are not replayed. The target must be localhost, 127.0.0.1, [::1] or a *.localhost name. Get it on the download page.

The 5 minute timestamp window applies, so resend fresh events only.

Questions

What is Standard Webhooks?

An open specification for sending and verifying webhooks. It defines three headers (webhook-id, webhook-timestamp, webhook-signature), an HMAC-SHA256 signature over id, timestamp and body, and recommendations for payloads, retries and replay protection. Svix, and services built on it such as Resend, use the same scheme with svix- header names.

How does Hooksmith verify a Standard Webhooks signature?

It builds the string <webhook-id>.<webhook-timestamp>.<raw body>, computes HMAC-SHA256 with the decoded whsec_ secret, base64 encodes the result and compares it in constant time with each v1 entry in webhook-signature. It also checks that the timestamp is within the tolerance, 5 minutes unless you set source.verification.tolerance.

Can I change the replay tolerance?

Yes. Under source.verification, set tolerance to a duration such as 10m or 300s. The default, and the value in the preset, is 5m.

How do retries and duplicates work?

The spec keeps webhook-id the same when a sender retries, and recommends using it as an idempotency key. Hooksmith does that for 24 hours, so a retry of an event it already accepted is acknowledged without a second delivery. To deliver an event Hooksmith already accepted again, use hooksmith replay <event-id>, which skips the duplicate check. Hooksmith answers 200 once the event is stored, then retries your endpoint itself on 5xx responses, 408, 425, 429 and network errors.

Does Hooksmith support asymmetric Standard Webhooks signatures?

No. Only the symmetric v1 scheme with a whsec_ secret is implemented. A request signed only with v1a fails verification.

Other providers

All providers are listed on webhook providers. Hooks are metered by events processed: see pricing.