Webhooks

Use webhooks when an external system pushes information into Cessy. A webhook should authenticate the sender, validate the payload, and map the payload into a modeled command.

Processing flow

1. Receive the external request.
2. Verify signature, token, or challenge.
3. Validate and normalize the payload.
4. Evaluate guard expressions.
5. Map payload data into command input.
6. Execute the command through the runtime pipeline.
7. Record success or failure in Activity and error logs.

Do not let a webhook bypass command validation or permissions.

Signature verification

Configure webhook auth based on the sender’s capabilities. Prefer signed requests. If the sender supports verification challenges, implement the challenge flow before accepting event delivery.

Raw-body HMAC

Use hmac-sha256 for providers that sign only the exact request body:

{
  "type": "hmac-sha256",
  "headerName": "x-hub-signature-256",
  "secretCredential": "GITHUB_WEBHOOK_SECRET",
  "signaturePrefix": "sha256="
}

Svix and Standard Webhooks

Use svix for Resend and other Svix-compatible providers. Cessy verifies the exact raw body together with svix-id, svix-timestamp, and svix-signature, accepts rotating v1 signatures, rejects timestamps outside the configured past or future tolerance, and atomically rejects a replayed delivery ID.

{
  "type": "svix",
  "secretCredential": "RESEND_WEBHOOK_SECRET",
  "toleranceSeconds": 300
}

toleranceSeconds must be an integer from 1 through 86,400. Store the provider’s whsec_... value in the referenced credential slot. Never place the secret itself in a Workspace, ChangeSet, Trigger definition, test fixture, or diagnostic payload. Temporary webhook diagnostics omit Svix request bodies entirely; signature header values are redacted.

Guard expressions

Use guards to reject irrelevant events early. Keep guards readable and tied to sender payload shape.

Deduplication

If the sender can retry, model idempotency deliberately. Svix verification provides transport-level replay rejection from svix-id; commands should still model business idempotency when the same business action can arrive under different delivery IDs. For other signature modes, include an external event ID in the command or configure a deduplication key.

Error behavior

Webhook errors should be observable:

• invalid auth
• invalid payload
• guard rejected
• mapping failed
• command validation failed
• downstream policy or adapter failed

External senders may retry, so design handlers to be safe under duplicate delivery.