> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cessy.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cessy.ai/_mcp/server.

# Webhooks

> Receive external events through Cessy webhook triggers and map authenticated payloads into modeled commands.

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:

```json
{
  "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.

```json
{
  "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.