API & webhooks
HTTP in. Signed events out. Clear failure modes in between.
These examples show the shape of Casewelt’s integration contracts. Endpoints and schemas are versioned with the environment you are issued.
Create a folder
Make retries safe.
A client should be able to retry a create request after a timeout without producing a second folder. An idempotency key gives the request a stable identity across those retries.
POST /v1/folders
Authorization: Bearer …
Idempotency-Key: 7a1f3b…
Content-Type: application/json
{
"parent_id": "fld_board",
"name": "Board pack"
}Errors
Make denial different from failure.
Operations teams need to know whether a request failed validation, hit an explicit policy decision, conflicted with governance state or referred to access that has already ended.
HTTP/1.1 403 Forbidden
{
"code": "policy_denied",
"policy_id": "pol_hr_no_external",
"request_id": "req_01…"
}Webhook receiver
Build for authentic delivery and normal retries.
Authenticate the sender over the timestamp and body before trusting the event.
Reject messages whose timestamp falls outside the accepted skew.
At-least-once delivery means receiving the same event again is a normal recovery path.
Return success only after the event has reached the boundary your system considers safe.
Webhook signing secrets should be treated as credentials and not written into application logs.
Timeouts and server failures should lead to bounded retry behaviour rather than silent loss.
Event envelope
Give downstream systems stable identity.
A well-formed event says what happened, when, to which object and under which organisation context. Consumers can then enrich or route it without parsing prose.
{
"id": "evt_01…",
"type": "share.content_read",
"occurred_at": "2026-08-19T11:04:00Z",
"object_id": "fil_01…",
"share_id": "shr_01…"
}Integration contract
Review the integration contract around your workflow.
We can discuss authentication, idempotency, events, retries and the operational evidence your integration needs.