Skip to main content

Webhook signature verification

Webhooks from third-party systems — Stripe payment events, GitHub repository events, Slack workspace events, Atlassian Connect callbacks — typically require the receiver to verify a signature on every inbound payload before processing it. The verification proves the payload came from the expected sender and was not tampered with in transit.

The platform handles signature verification at the API gateway — the extension's signing secret lives inside Kibo's hardware-attested enclave, the gateway verifies the signature before the extension's code runs, and a single failure response surfaces to the caller. Extension authors do not write signature-verification code for any of the standard schemes; the gateway does it once, correctly, for every extension.

1. The gateway-provided default​

For the 12 standard webhook signature schemes the platform supports (see §3 below), extension authors declare the scheme in their manifest and the gateway handles verification end-to-end:

  1. Inbound webhook arrives at the extension's declared webhookIngress[] endpoint
  2. Gateway fetches the signing secret from the per-project webhook_secrets table — secret material lives inside Kibo's enclave and the gateway holds an attested-channel reference, never the raw bytes
  3. Gateway verifies the signature per the declared scheme — checking HMAC, JWT signature, or scheme-specific structure against the secret
  4. On verification failure, the gateway returns 401 K9O_WEBHOOK_SIGNATURE_INVALID to the caller (the third-party sender's retry path); the extension's code is never invoked
  5. On verification success, the gateway invokes the extension's runtime function with the verified payload and request context
Senderthird-party systeminbound payloadGatewayverifies per schemesignature validExtensionruntime functioninvalid401 to senderK9O_WEBHOOK_SIGNATURE_INVALIDextension never invokedattested channelKibo enclaveholds the signing secretgateway keeps a reference
The extension runs only after the gateway has verified the signature, and it never holds the raw secret.

The structural property: extension code receives a payload that has already been authenticated. The signing secret never enters the extension's process address space. A compromised extension cannot leak the raw secret because the extension never had it.

2. What gateway-side verification gives you​

  • Security boundary — the signing secret stays in Kibo's enclave with attested-channel access. Extension code never holds it.
  • Correctness — signature verification is implemented once at the gateway; every scheme — timing-safe comparison, replay protection, header canonicalisation — is correct without per-extension cryptography expertise.
  • Operational simplicity — declare the scheme in the manifest; receive verified payloads.
  • Audit attribution — verification failures emit audit events with scheme name, reason code, and attempted-sender context. Failure patterns surface in the project's audit log automatically.

3. Standard scheme catalogue​

The platform supports 12 standard webhook signature schemes plus a custom escape value:

SchemeCoverage
stripe-v1Stripe webhook events (Stripe-Signature header with timestamp + HMAC-SHA256)
github-hmac-sha256GitHub repository / organisation / marketplace webhooks (X-Hub-Signature-256 HMAC-SHA256)
slack-v0Slack Events API + interactive messages (X-Slack-Signature v0 prefix with HMAC-SHA256 over timestamp + body)
sendgrid-v3-ed25519SendGrid Event Webhook (Ed25519 signature with public-key verification)
twilioTwilio webhook signature (X-Twilio-Signature HMAC-SHA1 over canonicalised request)
shopifyShopify webhooks (X-Shopify-Hmac-Sha256 base64 HMAC-SHA256)
linearLinear webhook signature (Linear-Signature HMAC-SHA256)
notionNotion automation / webhook signature
discordDiscord webhook + interaction signature (X-Signature-Ed25519 + X-Signature-Timestamp)
ms-teamsMicrosoft Teams outgoing webhook signature (HMAC-SHA256 with shared secret)
generic-hmac-sha256Generic HMAC-SHA256 fallback for vendors not on the named-scheme list but using a standard HMAC-SHA256 header pattern
atlassian-jwtAtlassian Connect apps (Jira Cloud, Confluence Cloud, Bitbucket Cloud) — signed JWT in Authorization header with qsh query-string-hash claim, iss issuer claim, and 3-minute expiry tolerance

The catalogue is a closed enumeration. New standard schemes are added through the platform's spec process; extensions cannot register their own standard scheme identifier.

4. The hybrid escape hatch — signatureScheme: custom​

For vendor signature schemes the platform has not standardised, the manifest can declare signatureScheme: custom. In the custom path the extension code holds and applies the signing material directly. Three guardrails apply:

GuardrailRationale
Warden review at extension publicationA custom-scheme extension surfaces explicitly during the curation programme review (see Build Your Own → Publishing and curation); the Warden role reviews the verification implementation against the platform's correctness criteria before publication
Console disclosure to the project adminWhen a project admin enables a custom-scheme extension, the Console surface displays the custom-scheme designation explicitly. The admin grants permission knowing the extension is on the escape path, not the standard path
Free-tier prohibitionCustom-scheme extensions cannot be enabled on Free-tier projects. The standard-scheme path is the only signature-verification path available on Free tier; custom requires a paid tier

The escape hatch exists for vendors with novel signature constructions the platform has not standardised. Once a vendor's scheme is widely-enough deployed to warrant standardisation, it migrates into the closed enumeration (see §3 above) and the extension switches from custom to the named scheme.

5. Secret rotation​

Each project that has enabled webhook-receiving extensions holds a per-project system table at k9o_<proj_id>_ext_<slug>.webhook_secrets storing the active and pending signing secrets per scheme. The secret material lives inside Kibo's enclave; the table stores references that the gateway resolves at verification time.

Rotation follows the dual-acceptance window pattern:

  1. New secret enrolled — the customer issues a new signing secret in the third-party vendor's surface; the platform Console or CLI records the new secret in the project's webhook_secrets table
  2. Dual-acceptance window opens — the gateway accepts signatures verified by either the previous or the new secret. Inbound webhooks arriving during the window verify against either secret
  3. Customer retires the previous secret in the third-party vendor's surface — the vendor stops signing with the old secret; only the new secret produces valid signatures going forward
  4. Customer closes the window in the Console or CLI — the gateway stops accepting signatures verified against the previous secret; the new secret is the sole active signer
New secretrecorded in Consoleor CLIWindow opensgateway accepts oldor new secretOld secret retiredvendor stops signingwith the old secretWindow closedold secret rejectednew is sole signerdual-acceptance windowwindow length is customer-configured
During the window a signature from either secret verifies; closing it leaves one signer.

The window length is customer-configured. A short window minimises the rotation footprint; a longer window accommodates third-party systems that take time to propagate the new secret across their distribution.

6. Failure surface​

Signature verification failures return 401 K9O_WEBHOOK_SIGNATURE_INVALID with a structured context payload identifying which scheme failed and the scheme-specific reason. The error reaches the third-party sender (which typically retries with backoff) and surfaces in the project's audit log for forensic review.

The context.scheme value is one of the 12 standard scheme values or custom. Scheme-specific context.reason values surface the failure mode:

SchemeReason values
atlassian-jwtmismatch (signature failed verification), qsh_mismatch (query-string-hash claim does not match canonical request), expired (JWT past 3-minute tolerance), iss_mismatch (issuer claim does not match enrolled app), unauthorized_app (issuer not associated with this extension installation)
HMAC-family schemes (stripe-v1, github-hmac-sha256, slack-v0, shopify, linear, notion, ms-teams, generic-hmac-sha256, twilio)mismatch (HMAC comparison failed), expired (timestamp outside accepted skew window where applicable), replay (request signature matches a recently-processed request — replay-protection trigger)
Ed25519 schemes (sendgrid-v3-ed25519, discord)mismatch (signature failed verification against public key), expired (timestamp outside accepted skew window)
customReason value is extension-defined; the extension's custom verification code surfaces its own reason via the gateway

The full error code definition lives at Specifications → Error Catalogue → K9O_WEBHOOK_SIGNATURE_INVALID.

7. Operational patterns​

  • Extension authoring — for standard-scheme extensions, declare webhookIngress[] in the manifest with the scheme name and the runtime function to invoke on verified payloads. No verification code lives in the extension.
  • Secret enrollment — the customer enrols the signing secret through the Console at extension-enable time or through the project's CLI. The secret is stored inside Kibo's enclave; the value is not exposed back to the caller after enrolment.
  • Audit-driven correlation — every verification (success or failure) emits an audit event with the scheme, the source IP, the request ID, and the context.reason on failure. A correlated dashboard surfaces verification health per extension.
  • Custom-scheme migration — extensions on the custom path that follow a vendor's pattern matching another standardised scheme should migrate to the named scheme on the next version bump; the standardised path is more secure (gateway-side enclave) and operationally simpler (no per-extension verification code).

8. See also​