Source Authentication

What Source Auth Protects

Source authentication answers one question: should FastHook accept this inbound provider request at all? It is evaluated on the Source before connection filters, transformations, retries, or destinations can run.

A rejected source-auth request is still useful evidence in Requests, but it does not create Events or Attempts. That keeps forged or malformed traffic away from downstream receivers.

• FastHook checks source state and allowed HTTP method first.
• Source auth runs before connection filters, transformations, and destinations.
• Accepted authenticated requests are marked verified.
• Rejected auth requests are stored as rejected with a failure reason.
• Destination signature verification is a separate outbound concern.

Check Order

When a request hits a source URL, FastHook evaluates the source boundary in a fixed order. This matters when debugging because a method rejection happens before auth, and an auth rejection happens before routing.

• Disabled sources reject before source auth.
• Methods outside allowed_http_methods are rejected with SOURCE_METHOD_NOT_ALLOWED.
• Auth failures are rejected with SOURCE_AUTH_FAILED.
• Only accepted requests move into connection fan-out.
• Accepted requests with no auth configured are accepted but unverified.

Provider request
  -> source exists and is enabled
  -> method is in config.allowed_http_methods
  -> config.auth_type is checked
  -> request stored as accepted or rejected
  -> accepted requests create connection events

Configure It In Dashboard

Open the source in the dashboard, enable Authenticate, choose the method, fill the method-specific fields, and save. The dashboard writes config.auth_type and config.auth on the Source.

The same source settings panel also controls allowed HTTP methods. Keep that list as narrow as the provider allows.

• HMAC fields: Secret, Signature header, optional Timestamp header, optional Prefix.
• API key fields: Header name and API key value. The default header name is x-api-key.
• Basic Auth fields: Username and Password.
• Allowed methods default to POST, PUT, PATCH, and DELETE in the dashboard code; enable GET only when a provider actually uses it.
• Turning Authenticate off writes auth_type: null and auth: null.

API Shape

The public API exposes source auth directly in the source config. Use PATCH when you want to update an existing source without replacing unrelated fields.

Send x-team-id with API-key automation when the key can access more than one team.

curl -X PATCH "https://api.fasthook.io/v1/sources/src_xxx" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "auth_type": "HMAC",
      "auth": {
        "secret": "whsec_provider_secret",
        "signature_header": "x-provider-signature",
        "timestamp_header": "x-provider-timestamp",
        "prefix": "sha256="
      },
      "allowed_http_methods": ["POST"]
    }
  }'

Choose The Auth Mode

Pick the mode that matches the sender's capabilities. HMAC is usually best for public provider webhooks because it binds the signature to the body. API key and Basic Auth are useful for simpler internal producers or providers with limited auth controls.

• BASIC_AUTH reads Authorization: Basic and compares username and password.
• API_KEY reads a configured header, defaulting to x-api-key.
• HMAC signs the raw body or timestamp.rawBody with HMAC-SHA256.
• HMAC can match provider prefixes such as sha256=.
• No auth_type means FastHook can accept the request but it appears unverified.

Basic Auth Source

Use BASIC_AUTH when the sender can provide an Authorization: Basic header. FastHook compares the configured username and password before accepting the request.

{
  "config": {
    "auth_type": "BASIC_AUTH",
    "auth": {
      "username": "provider-user",
      "password": "provider-password"
    },
    "allowed_http_methods": ["POST"]
  }
}

curl.exe -X POST "https://hook-xxxxxx.fasthook.io/" -u provider-user:provider-password -H "content-type: application/json" -d "{""type"":""ping""}"

API Key Source

Use API_KEY when the sender can add a static secret header. If header_name is omitted in the source config, FastHook uses x-api-key.

{
  "config": {
    "auth_type": "API_KEY",
    "auth": {
      "header_name": "x-provider-token",
      "value": "provider-secret-token"
    },
    "allowed_http_methods": ["POST"]
  }
}

curl.exe -X POST "https://hook-xxxxxx.fasthook.io/" -H "x-provider-token: provider-secret-token" -H "content-type: application/json" -d "{""type"":""ping""}"

HMAC Source

Use HMAC when the provider signs webhook payloads. FastHook computes an HMAC-SHA256 hex digest over the exact raw request body, or timestamp.rawBody when timestamp_header is configured and present.

The signature header must contain the digest FastHook should compare. If the provider prepends a scheme such as sha256=, set prefix to that string.

{
  "config": {
    "auth_type": "HMAC",
    "auth": {
      "secret": "whsec_provider_secret",
      "signature_header": "x-provider-signature",
      "timestamp_header": "x-provider-timestamp",
      "prefix": "sha256="
    },
    "allowed_http_methods": ["POST"]
  }
}

Test HMAC With Curl

When testing by hand, compute the signature from the exact body string that curl sends. Any whitespace, key order, or line-ending change will produce a different digest.

$BODY = "{""type"":""ping"",""id"":""evt_123""}"
$TIMESTAMP = [string][int][double]::Parse((Get-Date -UFormat %s))
$INPUT = "$TIMESTAMP.$BODY"
$HMAC = New-Object System.Security.Cryptography.HMACSHA256
$HMAC.Key = [Text.Encoding]::UTF8.GetBytes("whsec_provider_secret")
$DIGEST = -join ($HMAC.ComputeHash([Text.Encoding]::UTF8.GetBytes($INPUT)) | ForEach-Object { $_.ToString("x2") })

curl.exe -X POST "https://hook-xxxxxx.fasthook.io/" -H "content-type: application/json" -H "x-provider-timestamp: $TIMESTAMP" -H "x-provider-signature: sha256=$DIGEST" -d $BODY

GitHub HMAC Preset

For GitHub webhooks, configure FastHook to read X-Hub-Signature-256. GitHub signs the raw request body and prefixes the digest with sha256=.

• Leave timestamp_header empty for GitHub.
• Use the same secret value configured in the GitHub webhook settings.
• Do not use the older SHA-1 x-hub-signature header for new integrations.

{
  "config": {
    "auth_type": "HMAC",
    "auth": {
      "secret": "same value as GitHub webhook Secret",
      "signature_header": "x-hub-signature-256",
      "prefix": "sha256="
    },
    "allowed_http_methods": ["POST"]
  }
}

What Verified Means

The Requests verified flag is about source authentication only. It does not prove a destination received or processed the event.

An accepted request can be verified=false when the source has no auth configured. That is expected for intentionally unauthenticated sources, but it is not appropriate for public production provider traffic.

• accepted + verified=true: source auth was configured and passed.
• accepted + verified=false: source auth was not configured.
• rejected + SOURCE_AUTH_FAILED: source auth was configured and failed.
• rejected + SOURCE_METHOD_NOT_ALLOWED: method was not allowed for the source.
• Events and Attempts only appear after FastHook accepts the request.

Inspect Auth Results With API

Use the Requests API when you need to audit source auth in a runbook or CI smoke test. Add include=data only when you need stored headers or body details.

curl "https://api.fasthook.io/v1/requests?from=now-1h&to=now&source_id=src_xxx&status=accepted&verified=true&include=data&limit=20" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_xxx"

curl "https://api.fasthook.io/v1/requests?from=now-1h&to=now&source_id=src_xxx&status=rejected&include=data&limit=20" \
  -H "Authorization: Bearer fhp_xxx" \
  -H "x-team-id: tm_xxx"

Testing Auth

• Send one valid provider test event and confirm verified is true.
• Send invalid test traffic only in staging when proving rejection.
• Inspect rejected Requests for SOURCE_AUTH_FAILED or method failures.
• Keep raw body stable when testing HMAC signatures.
• Do not parse and re-stringify JSON before computing test signatures.

Troubleshooting

• No request appears: the sender did not call the FastHook source URL, or the wrong environment URL was used.
• SOURCE_METHOD_NOT_ALLOWED: add the method to allowed_http_methods or send the method the source expects.
• SOURCE_AUTH_FAILED with Basic Auth: confirm the sender uses Authorization: Basic and the configured username/password.
• SOURCE_AUTH_FAILED with API key: confirm the header name and exact value, including whitespace.
• SOURCE_AUTH_FAILED with HMAC: confirm raw body, secret, signature_header, timestamp_header, and prefix.
• Accepted but unverified: auth_type is null, so source auth is not enabled.
• Provider test still fails after FastHook accepts: check custom source response expectations and downstream Events separately.

Operational Rules

• Enable source auth for every public production provider source.
• Use separate secrets per provider and environment.
• Narrow allowed_http_methods to the methods the provider actually uses.
• Rotate provider secrets after exposure.
• Keep receiver-side idempotency even when source authentication passes.
• Do not reuse provider production HMAC secrets in staging.
• Document each source's auth_type, signature header, and rotation owner.
• Keep destination delivery signatures on their own guide and config path.

Next

• Webhook signature validation
• Sources
• Custom source responses
• Destination delivery signatures