Skip to main content
Version: MVP

Webhook ingress

2 min readReferenceUpdated 2026-05-19

What you'll find here

The validation boundary for one webhook request — signature checks, payload-size checks, JSON parsing, timestamp freshness, event-id idempotency, event-type authorization, replay protection, and redacted ingress receipts.

Validation, not authority.

Webhook validation does not grant channel authority. Accepted events still need channel policy, allowlist, identity, and capability checks before any privileged gateway action.

What it provides​

craik.runtime.webhook_ingress covers:

HMAC SHA-256 signature validation

Payload size cap

Oversized bodies are rejected before parsing.

JSON object parsing

JSON nesting-depth limit

Required event_id & event_type extraction

Timestamp freshness

Events outside the allowed window are rejected.

Idempotency checks

Against known and persisted event ids.

Event-type authorization

Redacted ingress receipts

Signature​

Requests use one X-Craik-Signature header. Header names are handled case-insensitively, and ambiguous duplicate signature headers fail closed.

sha256=<hex digest>

The digest is computed over the raw request body with the configured webhook secret. Missing or invalid signatures are rejected before JSON parsing.

Event shape​

Field
Required
Notes
event_id
required
Duplicate ids are rejected before dispatch.
event_type
required
Only configured event types are accepted.
timestamp
required
Must be inside the configured freshness window.
payload
optional object
Application-specific.

Safe dispatch​

Accepted results include a dispatch_payload containing the event id, event type, and object payload. The helper does not perform side effects or enqueue work by itself.

Receipts​

Webhook ingress receipts use the webhook.ingress capability. Receipt metadata preserves event id, event type, policy envelope id, ingress status, and redaction fields. Raw body, signatures, and payload content are not stored in receipt metadata.

What's next​

ReferenceGateway receiptsThe receipt shape ingress produces.ReferenceChannel policy envelopesThe next stage in the gateway pipeline.GuideGateway troubleshootingDiagnose webhook failures.