Share opened or revoked
Close the loop in your matter file when the auditor actually saw the pack, or when you pulled it back.
Events
HTTP in. Signed events out. A reason when either fails.
These are the live organisation contracts, not sketches. Endpoints version with /v1. Recipients still do not use your Bearer token. For authentication, files and shares, use the pages beside this one.
Register a destination
Name a URL. Casewelt keeps the deliveries.
Scope webhooks. Signing secrets are shown once. Later reads tell you that a secret exists, not what it is. Administrators can list deliveries and replay one that your side missed.
POST /v1/webhooks
Authorization: Bearer …
Idempotency-Key: 7a1f3b…
Content-Type: application/json
{
"url": "https://example.com/casewelt/events",
"types": ["share.content_read", "share.revoked"]
}Errors
Make denial different from failure.
Operations need to know whether the body was wrong, policy said no, governance blocked the state change, or the share has already ended. Problem documents carry a short code as well as the HTTP status.
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
{
"title": "Forbidden",
"status": 403,
"code": "policy_denied",
"correlation_id": "94f0…"
}When a delivery arrives
Verify, then accept once.
GET and POST /v1/webhooks manage destinations. Signing secrets are shown once. Reads later tell you that a secret exists, not what it is. Administrators can list deliveries and replay one that your side missed.
Verify the signature
Authenticate the sender over the timestamp and body before trusting the event.
Check replay window
Reject messages whose timestamp falls outside the accepted skew.
Deduplicate by event ID
At-least-once delivery means receiving the same event again is a normal recovery path.
Acknowledge after durable accept
Return success only after the event has reached the boundary your system considers safe.
Protect secrets
Webhook signing secrets are credentials. Do not write them into application logs.
Expect retries for 72 hours
Timeouts and server failures lead to bounded retry, then a delivery you can replay by hand.
Event envelope
Say what happened, to which object, for which organisation.
Consumers route on type and identifiers. They do not parse a sentence. The body is not the file bytes. Those still come through Casewelt transfer if you are allowed to have them.
{
"id": "evt_01…",
"type": "share.content_read",
"occurred_at": "2026-08-19T11:04:00Z",
"object_id": "fil_01…",
"share_id": "shr_01…"
}Types you will actually subscribe to
Start with the moments a neighbouring system must notice.
File arrived inbound
A file request completed. Kick the next step without polling the folder.
Signature progressed
An envelope was sent, a signer finished, or the completed version filed.
Policy refused
Someone tried a share that must not happen. Your monitoring should see a denial, not a missing success.
Hold blocked a delete
Records teams need that as an event, not as a rumour from a helpdesk ticket.
Quota or usage
Stop filling a dead letter with uploads that will never be accepted.
Integration contract
Review authentication, events and the failure you care about.
Bring the URL that should receive opens. We will sign a delivery, retry it, and show a replay from the console.