Webhook Verification#

Every endpoint verifies a delivery before it starts a run. The verification method decides which headers, credentials, and replay checks apply. Choose the method that matches the producer. Standard Webhooks is the default.

Choose a Method#

Method Use when Credentials Replay protection
Standard Webhooks The producer follows the Standard Webhooks specification. A whsec_ signing secret. Signed timestamp and delivery ID.
Provider preset The producer is Shopify, GitHub, Stripe, Paddle, Square, Typeform, Calendly, Slack, HubSpot, or Zendesk. The provider’s signing secret. The provider’s delivery ID, when available.
API key or token The producer sends a shared token in a header. A header name, optional prefix, and token. None.
Custom signing secret The producer signs the raw request body with HMAC. A shared secret and a signature header. Delivery ID header when configured.
Unverified URL The sender cannot sign requests and you accept the risk. None. None.

This page documents the methods currently available for new endpoints.

Standard Webhooks#

Use Standard Webhooks when the producer follows the Standard Webhooks specification. This is the default method for new endpoints.

Send a JSON POST request to the endpoint URL with these headers:

Header Value
Content-Type application/json
webhook-id A unique ID for this delivery.
webhook-timestamp Unix time in seconds.
webhook-signature v1, followed by the base64 signature.

The signature is an HMAC-SHA256 hash of the delivery ID, the timestamp, and the raw request body, joined with dots:

HMAC-SHA256(secret, "{webhook-id}.{webhook-timestamp}.{raw body}")

The webhook-signature header may contain more than one space-separated v1,... signature, as Standard Webhooks permits. GearTrain accepts the delivery when any v1 signature matches.

Use the signing secret exactly as the sender provided it, including the whsec_ prefix. The prefix is not part of the key: decode the base64 text after it to get the HMAC key. The secret must decode to 24 to 64 bytes. The request body must be valid JSON and no larger than 256 KB. Timestamps more than five minutes from GearTrain’s server time are rejected.

A whsec_ prefix does not always mean this key rule. Stripe, for example, uses the full secret string as the key. Use the rule documented for the method you select.

Example Sender#

This example runs in a terminal or on the sender, not inside the GearTrain sandbox. It uses curl and openssl. The --data-binary flag sends the exact body that was signed.

#!/usr/bin/env bash
set -euo pipefail

ENDPOINT="https://app.geartrain.dev/hooks/wh_..."
SECRET="whsec_..."
BODY='{"event":"payment.succeeded","id":"pay_123"}'
ID="msg_$(date +%s)"
TIMESTAMP="$(date +%s)"

# Decode the base64 key after whsec_ into hex for openssl.
KEY_HEX="$(
  printf '%s' "${SECRET#whsec_}" \
    | openssl base64 -d -A \
    | od -An -tx1 \
    | tr -d ' \n'
)"

SIGNATURE="$(
  printf '%s.%s.%s' "$ID" "$TIMESTAMP" "$BODY" \
    | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$KEY_HEX" -binary \
    | base64
)"

curl -X POST "$ENDPOINT" \
  -H "Content-Type: application/json" \
  -H "webhook-id: $ID" \
  -H "webhook-timestamp: $TIMESTAMP" \
  -H "webhook-signature: v1,$SIGNATURE" \
  --data-binary "$BODY"

Provider Presets#

Choose the provider on the add endpoint page and paste its signing secret. GearTrain uses the provider’s signing rules, so you do not need to configure headers, algorithms, or encodings.

The verification method and secret are fixed when you create an endpoint. To change either, delete the endpoint and add a new one. The endpoint URL changes, so update the provider with the new URL.

After you save an endpoint, GearTrain shows the endpoint URL and short setup steps for the selected provider.

Expand a provider for the GearTrain-specific checks. Use the provider’s own documentation for account setup, event selection, and credential rotation.

Shopify: signing secret and webhook ID dedupe

Shopify#

Choose Shopify and paste the signing secret from the webhook.

GearTrain verifies X-Shopify-Hmac-Sha256 and uses X-Shopify-Webhook-Id for duplicate suppression.

Shopify webhook documentation

GitHub: shared secret and delivery ID dedupe

GitHub#

Choose GitHub and enter the same secret you set on the webhook.

GearTrain verifies X-Hub-Signature-256 and uses X-GitHub-Delivery for duplicate suppression.

GitHub webhook documentation

Stripe: timestamped signature and event ID dedupe

Stripe#

Choose Stripe and paste the whsec_ signing secret exactly as Stripe shows it.

Stripe signs with the full whsec_ string as the HMAC key. Do not base64-decode it the way Standard Webhooks requires.

GearTrain verifies Stripe-Signature, accepts any matching v1 signature, enforces the five-minute timestamp tolerance, and uses the event ID for duplicate suppression.

Stripe webhook documentation

Paddle: timestamped signature and event ID dedupe

Paddle#

Choose Paddle and paste the notification destination secret key. Paddle Billing keys start with pdl_ntfset_.

GearTrain verifies Paddle-Signature, which carries ts and one or more h1 values. It signs the timestamp and raw body with HMAC-SHA256 using the full secret string, accepts any matching h1, enforces the five-second timestamp tolerance, and uses event_id for duplicate suppression.

Paddle webhook documentation

Square: notification URL plus body signature

Square#

Choose Square and paste the subscription signature key.

GearTrain verifies x-square-hmacsha256-signature over the exact notification URL followed by the raw body. The notification URL in Square must match the GearTrain endpoint exactly. It uses event_id for duplicate suppression.

Square webhook documentation

Typeform: prefixed body signature and event ID dedupe

Typeform#

Choose Typeform and use the same secret you set in the form’s webhook settings.

GearTrain verifies Typeform-Signature with the sha256= prefix and uses event_id for duplicate suppression.

Typeform webhook documentation

Calendly: timestamped signature without dedupe

Calendly#

Choose Calendly and paste the webhook signing key.

GearTrain verifies Calendly-Webhook-Signature, enforces the three-minute timestamp tolerance, and does not apply duplicate suppression because Calendly does not provide a reliable delivery ID.

Calendly webhook documentation

Slack: challenge response and event ID dedupe

Slack#

Choose Slack and paste the signing secret from Basic Information.

When you save the Request URL, Slack sends a url_verification event. GearTrain verifies the signature and returns the challenge immediately without starting a run. It verifies X-Slack-Signature, enforces the five-minute timestamp tolerance, and uses event_id for duplicate suppression.

Slack Events API documentation

HubSpot: v3 signature over the method, URL, body, and timestamp

HubSpot#

Choose HubSpot and paste the app client secret.

GearTrain verifies X-HubSpot-Signature-v3 over the request method, the exact endpoint URL, the raw body, and the millisecond timestamp. It enforces the five-minute tolerance. HubSpot batches events, so GearTrain does not apply request-level duplicate suppression. Deduplicate individual events in the script with eventId and portalId.

HubSpot webhook documentation

Zendesk: timestamped signature and event ID dedupe

Zendesk#

Choose Zendesk and paste the webhook signing secret. Choose the JSON body format for the webhook.

GearTrain verifies X-Zendesk-Webhook-Signature, a base64 HMAC-SHA256 of the X-Zendesk-Webhook-Signature-Timestamp value followed by the raw body. It enforces the five-minute timestamp tolerance and uses the event id for duplicate suppression.

Zendesk webhook documentation

Request a Provider#

We add presets based on demand. If your provider is missing, email [email protected] with:

  • the provider name;
  • a link to its webhook documentation;
  • the events you want to receive.

Custom Signing Secret#

Use a custom signing secret when the producer signs the raw request body with HMAC but does not use Standard Webhooks. Create the endpoint with the generic-hmac source type and provide:

  • the signature header name;
  • the digest algorithm (sha1, sha256, or sha512);
  • the signature encoding (hex, base64, or base64url);
  • the shared secret;
  • an optional signature prefix, such as sha256=;
  • an optional delivery ID header.

GearTrain computes HMAC over the raw request body and compares it in constant time. There is no signed timestamp in this mode.

When a delivery ID header is configured, GearTrain uses it for duplicate suppression. When it is absent, GearTrain generates a delivery ID for the run and does not suppress duplicate bodies.

Several services send HMAC signatures over the raw body and work with this method: Linear, Jira Cloud admin webhooks, Vercel, Lemon Squeezy, and Docusign. Their documentation states the header, algorithm, encoding, and any prefix, which map to the fields above. Signatures that include a timestamp, or credentials generated by the provider, need a dedicated preset.

The example assumes a POSIX shell with curl and openssl.

#!/usr/bin/env bash
set -euo pipefail

ENDPOINT="https://app.geartrain.dev/hooks/wh_..."
SECRET="the-shared-secret"
BODY='{"event":"order.created","id":"ord_1001"}'
DELIVERY_ID="delivery_1001"

SIGNATURE="$(
  printf '%s' "$BODY" \
    | openssl dgst -sha256 -hmac "$SECRET" -hex \
    | awk '{print $NF}'
)"

curl -X POST "$ENDPOINT" \
  -H "Content-Type: application/json" \
  -H "X-Signature: sha256=$SIGNATURE" \
  -H "X-Delivery-Id: $DELIVERY_ID" \
  --data-binary "$BODY"

The matching endpoint settings use the same values:

{
  "sourceType": "generic-hmac",
  "secret": "the-shared-secret",
  "verification": {
    "signatureHeader": "X-Signature",
    "algorithm": "sha256",
    "encoding": "hex",
    "prefix": "sha256=",
    "idHeader": "X-Delivery-Id"
  }
}

API Key or Token#

Use an API key when the producer can send a shared value in a header but cannot sign the request body. Create the endpoint with the api-key source type and provide:

  • the header name, such as X-API-Key or Authorization;
  • an optional value prefix, such as Bearer or Zoho-oauthtoken ;
  • the token.

GearTrain compares the token in constant time. A missing header, a wrong prefix, or a wrong token returns 401. GearTrain does not check the Content-Type header, but a request that declares a JSON content type must still contain valid JSON; otherwise it returns 400 invalid_payload. This mode does not provide replay protection because there is no signed timestamp.

The token is stored encrypted and is never shown again. Changing it means deleting the endpoint and creating a new one, which also changes the endpoint URL.

Header Token Example#

#!/usr/bin/env bash
set -euo pipefail

ENDPOINT="https://app.geartrain.dev/hooks/wh_..."
TOKEN="token_abc123"
BODY='{"event":"record.created","id":"rec_1001"}'

curl -X POST "$ENDPOINT" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $TOKEN" \
  --data-binary "$BODY"

Use these endpoint settings:

{
  "sourceType": "api-key",
  "secret": "token_abc123",
  "verification": {
    "apiKeyHeader": "X-API-Key",
    "apiKeyPrefix": ""
  }
}

Authorization Prefix Example#

Some producers send the token as part of the Authorization header. Set the prefix to the text before the token, including its trailing space. For example, Zoho CRM can send Authorization: Zoho-oauthtoken <token>.

curl -X POST "$ENDPOINT" \
  -H "Content-Type: application/json" \
  -H "Authorization: Zoho-oauthtoken $TOKEN" \
  --data-binary "$BODY"

The matching verification settings are:

{
  "apiKeyHeader": "Authorization",
  "apiKeyPrefix": "Zoho-oauthtoken "
}

Unverified URL#

Use an unverified endpoint only when the sender cannot sign requests and you accept that anyone with the URL can start a run. Create the endpoint with the unverified source type. No secret is used; if a tool supplies one, GearTrain ignores it and stores none.

The opaque endpoint URL is the only capability. GearTrain does not check a signature, token, timestamp, or sender identity. Deliveries start a run immediately, and context.delivery.verified is false.

Because there is no trusted delivery ID, GearTrain generates one for each request and does not suppress duplicates. Treat the URL as a secret. Do not publish it, commit it, or place it in logs.

curl -X POST "$ENDPOINT" \
  -H "Content-Type: application/json" \
  --data-binary '{"event":"record.created","id":"rec_1001"}'

Failure Handling#

All methods return 401 invalid_signature when verification fails. GearTrain does not fall back to accepting an unverified delivery.

When a delivery is rejected:

  • confirm the secret matches the one configured on the endpoint;
  • confirm the sender signs the exact raw request body;
  • check the signature header name, algorithm, encoding, and prefix;
  • for API key sources, check the credential header, prefix, and token;
  • for Standard Webhooks, check the timestamp and delivery ID headers;
  • confirm the content type is accepted by the selected method.

Reference#