Webhooks

Webhooks allow external systems to trigger Quoderat runs and receive notifications when runs complete.

A webhook “success” response is not evidence; only a finalized envelope is.

What this page can (and cannot) claim

✓
Mechanical claims

• Triggering: A webhook request can initiate a run by recording an intent.
• Capture: The inbound payload—or a filtered representation—can be stored as an artifact with a sha256 identity.
• Correlation: The envelope can record correlation identifiers (event_id, delivery_id, provider) for traceability.
• Finalization: The authoritative output is a finalized Evidence Envelope with an integrity.hash_chain.

✗
No-claims

• No delivery guarantees: Webhooks are not guaranteed exactly-once, ordered, or replayable unless evidenced by artifacts you store.
• No default authenticity: Provider signatures only matter if you verify and record the result; otherwise treat payloads as untrusted input.
• No secrecy guarantee: Payloads often contain sensitive data; safety depends on policies and storage choices.

Mental model

Webhook in → Intent recorded → Work executed → Receipts captured → Envelope sealed

The webhook represents how the work was requested, not proof the work happened.

Golden path (recommended ingestion)

1. Verify (recommended)

• If the provider supports request signing (HMAC or similar), verify at ingestion.
• Record the outcome as an observation that cites the request bytes and/or signature headers as basis artifacts.

2. Normalize

Capture a minimal subset for correlation:

• provider — GitLab, GitHub, Jira, PagerDuty, …
• event_type
• external_event_id / delivery_id
• actor (if present)
• project/repository identifiers
• ref and/or commit_sha (when available)

3. Record

Store the request as an artifact:

• kind: webhook_request
• identity: sha256 of the bytes
• location: content_uri or location_hint

Optionally store headers separately (webhook_headers) if needed for later verification/audit.

4. Trigger execution

Create a run with an explicit intent, e.g.:

• “Run CI verification for commit <sha>”
• “Produce report-only security scan”

If commit_sha is not available yet, document that evidence cannot be anchored to an immutable code state until a commit is provided.

Mapping webhook → Evidence Envelope

Illustrative; adapt to your integration.

intent

Derived from event_type + target context

subject

• id: prefer commit_sha when present
• meta: event_id, delivery_id, project_path, mr_iid, etc. (non-authoritative)

artifacts[]

• webhook_request (raw or filtered)
• webhook_headers (optional)

observations[]

• signature_verified: true/false (verifiable only when citing basis_artifact_ids)
• Correlation IDs recorded (verifiable only when citing basis_artifact_ids)

Failure modes you should expect

Duplicates

Providers retry delivery; your handler must be idempotent.

Out-of-order

Events can arrive late; correlation must not assume ordering.

Partial context

Events may reference branches/MRs without commit_sha.

Oversharing

Payloads may contain emails/tokens/internal URLs; store defensively.

Idempotency guidance

Use provider delivery_id/event_id as a dedupe key.
On redelivery: either no-op, or attach as an additional artifact/observation to the existing run.
Finalized envelopes are append-only: never overwrite or mutate a sealed envelope due to a duplicate trigger.

Public vs internal sharing

Internal envelope

May include raw payload artifacts for deep audit.

Public pack

Strip payload artifacts by default unless explicitly allowlisted; rely on redactions[] receipts to show what was masked.

Implementation checklist

Decide storage policy: raw payload vs filtered subset.
Ensure payload artifacts are hashed and addressable.
Record correlation IDs.
Prefer commit_sha anchoring as soon as available.
Design explicitly for retries/duplicates/out-of-order delivery.
Validate proof by fetching the finalized Evidence Envelope, not by trusting webhook delivery success.

Next steps

GitLab Integration — commit_sha anchoring and CI pipeline context
CI/CD Integration — pipeline-to-envelope mapping
Policies — allowlists, redaction rules, internal vs public
Events (SSE) — real-time run signals (transient, not authoritative)
API Reference — programmatic envelope fetch and validation