Skip to main content

​
Inbound Webhooks overview

KnoxCall’s Inbound Webhooks feature is a signature-verifying ingress for HMAC-signed webhooks. Point Stripe (or GitHub, Slack, AWS SNS, anything that signs requests) at a KnoxCall URL. KnoxCall verifies the signature, audits the call, and optionally forwards the request to your app with an X-Knox-Verified: true header. The job your app would do — verify the HMAC, enforce the replay window, log the result — lives once in KnoxCall instead of being copy-pasted across every service that consumes webhooks.

​
Why use it

​
How it works

  1. Create an inbound webhook subscription in the admin UI — pick a format (Stripe, GitHub, Slack, AWS SNS, KnoxCall legacy, or custom-header), paste the shared secret, choose where to forward verified requests.
  2. KnoxCall hands you a receiver URL: https://hooks.knoxcall.com/<your_tenant_slug>/<webhook_name>.
  3. Paste that URL into the upstream provider’s webhook config. Stripe (or whoever) signs every event with HMAC-SHA256 of the body and sends it to KnoxCall.
  4. KnoxCall verifies the signature using the format’s wire spec and the secret you configured.
  5. If valid → forward to your app with X-Knox-Verified: true (or audit-only if no forward URL).
  6. If invalid → return 401 (default), or forward with X-Knox-Verified: false if you want your app to log unverified events without losing them.
Either way, the call lands in API Logs so you can see verification rate, replay-rejected requests, and forward latency.

​
Quick start (UI)

  1. Go to Automation → Webhooks in the admin UI, switch to the Inbound tab, and click New Inbound Webhook.
  2. Pick the format that matches the upstream provider (Stripe, GitHub, Slack, etc.).
  3. Paste the shared secret the provider gave you (e.g. Stripe’s whsec_...).
  4. Optional: enter a forward URL (your app’s webhook handler). Leave blank for verify-only auditing.
  5. Save. Copy the receiver URL that appears.
  6. Paste the receiver URL into the upstream provider’s webhook configuration.
That’s it. The next event from the upstream provider will hit KnoxCall, get verified, and either show up in your app’s webhook handler with X-Knox-Verified: true or appear in API Logs for inspection.

​
Supported formats

See the format guide for the exact wire format each verifier expects.

​
Replay protection

For formats with a timestamp header (Stripe, Slack), KnoxCall enforces a 5-minute window by default. A request with a timestamp older than that gets rejected with replay_window_exceeded even if the signature is valid. This closes the attack where someone captures a real webhook and replays it later. Configure the window per subscription (range: 0–86400 seconds, where 0 disables the check). The default of 300 matches Stripe’s and Slack’s recommended values.

​
What gets audited

Every ingest call writes a row to API Logs (/logs) with:
  • path — /<tenant_slug>/<webhook_name>
  • signature_valid — true / false
  • signature_error — the rejection reason if invalid (replay_window_exceeded, no v1 signature matched, missing X-Hub-Signature-256 header, etc.)
  • meta_json.subscription_id — which subscription handled the request
  • meta_json.forwarded — whether the verified request was sent on to your app
  • meta_json.forward_status — HTTP status from your app
Filter the logs by webhook name to see verification health for one provider.

​
Security model

KnoxCall stores the shared secret encrypted under the per-tenant master key (KCT1 envelope). The receiver URL is unauthenticated by design — authentication is the HMAC signature. A request that doesn’t verify either gets dropped (default) or marked X-Knox-Verified: false for your app to handle. Forwarding is SSRF-safe: the forward URL is validated to use HTTPS, point at a DNS hostname (not a literal IP), and not resolve to a private / metadata-IP range.

​
Next steps