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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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, orsha512); - the signature encoding (
hex,base64, orbase64url); - 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-KeyorAuthorization; - an optional value prefix, such as
BearerorZoho-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.