Product ability: A Webhook App is the durable receive boundary for external events: domain endpoints, verify templates, ingress policies, an inspectable inbox, and destinations that fan out into workflows, Event Apps, Knowledge, Surfaces, or URLs you own.
Skipped destination conditions are not failures. Provider response mode (immediate, static, or destination-owned) is separate from async fan-out.
Continue with SDK helpers for public URL builders and outbound signature verification.
Webhook Apps are Cliodot’s managed entry point for inbound events from the outside world — payments, CRM updates, messaging platforms, banking alerts, IoT devices, internal tools, and anything else that calls your URL when something happens.
Instead of every team building and maintaining its own receive stack (endpoints, signatures, retries, logs, replay, rate limits), you create a Webhook App, add endpoints, and decide what should happen when something arrives.
The goal:
Receive every webhook reliably, make it observable, and route it anywhere in or outside Cliodot.
Provider POST → tenant domain receive URL
↓
Verify + access guards
↓
Inbox (inspect / search / replay)
↓
Destinations (workflows, Event Apps, Knowledge, Surfaces, or your URLs)What Webhook Apps replace#
Without a Webhook App, each integration tends to reinvent:
- public endpoints per provider
- signature and auth checks
- retries and failure handling
- logging and debugging
- replay when something breaks
- routing into workflows or services
Webhook Apps centralize that operational work so developers focus on what the event should do, not on hosting another receive service.
What the Webhook ability gives you#
| Ability | Meaning |
|---|---|
| Apps | A named inbound product boundary (slug, project, status) that owns endpoints and shared policies |
| Endpoints | Domain-bound receive URLs — many per app — each with its own verify settings, access rules, and destinations |
| Verify templates | Match how the sender signs (provider presets, Cliodot, custom HMAC/compare, or none) without writing verify code per integration |
| Ingress policies | Reusable access rules shared across endpoints in the app — or custom rules on one endpoint |
| Destinations | Fan-out after accept: workflow, Event App, Knowledge, Surface, or an external URL you own |
| Conditions | Optional rules on a destination — non-matches are skipped, not failures |
| Inbox | Every arrival kept for inspection — headers, payload, status, delivery history, search, replay, resend |
| Provider response | Control what the sender gets back (immediate ACK, static reply, or one destination as response owner) while other routes still fan out |
| Observability | Metrics for receives, routing success/failure, throughput, dead letter, pending work, and guard rejects |
Routing is configured, not hardcoded. The public endpoint can stay stable while destinations and policies evolve.
Typical uses: payment notifications, order updates, CRM changes, HR or banking alerts, CI/CD callbacks, messaging platform events, device telemetry.
How a receive works#
- A provider POSTs to your public receive URL on a verified tenant domain.
- Cliodot applies the endpoint’s verify settings (or skips verify when the template is none).
- Access guards run — from an assigned ingress policy or the endpoint’s own rules (methods, rate limits, size, IP/host/UA allowlists).
- The receive is recorded in the inbox.
- Active destinations are evaluated; matching ones are delivered. Condition misses show as skipped.
- The provider response mode decides the HTTP reply to the sender — independently of async fan-out where applicable.
Replay and resend re-run destination evaluation from inbox history so you can recover without asking the provider to fire again.
Verify, access, and response#
Verify is per endpoint. Presets cover common providers; custom covers HMAC or header-secret compare; none turns verification off. A signing secret is only required when verification is on — and when Cliodot shows one, treat create/regenerate as copy-once.
Access prefers named ingress policies on the app (assign to endpoints, preview effective rules). An endpoint can use inline access instead when no policy is assigned. Empty allowlists mean “allow any” for that dimension; rate and concurrency limits can be disabled with 0.
Response to the provider can be:
| Mode | Behavior |
|---|---|
| Immediate | Acknowledge quickly after accept (default) |
| Static | Fixed status / headers / body — no wait on destinations |
| Destination-owned | One active workflow or outbound webhook destination produces the reply; others still enqueue async; fallback applies on skip/timeout/error |
Destinations#
Each destination is a route off an endpoint:
- Workflow — trigger a named workflow
- Event App / Knowledge / Surface — hand the event into other Cliodot products
- External URL — deliver to a URL you own (Cliodot signs outbound deliveries)
Optional conditions (body/header rules and/or an expression) decide whether that destination runs. Empty condition = always forward. Skipped deliveries are visible in inbox and delivery history — they are not treated as hard failures.
Destination test and delivery history let you see whether a condition matched and what request/response looked like on each attempt.
Portal vs SDK#
Most of Webhook Apps lives in the portal: create the app, endpoints, verify templates, ingress policies, destinations, inbox, replay, and metrics.
The SDK helps with two runtime/integration tasks:
- Build the public receive URL for an endpoint
- Verify signatures when Cliodot delivers outbound to a URL you own
Inbound provider verification is performed by Cliodot from the endpoint’s verify settings — the SDK does not re-verify inbound provider signatures.
Providers POST to your tenant domain:
https://{tenant-domain}/webhook/{appSlug}/{endpointSlug}