Event reference

There are nineteen event codes. The set is closed: you choose which of them an endpoint receives, and a code outside this list is refused when you save the selection rather than stored and quietly ignored.

Each endpoint has its own selection, and saving a selection replaces the previous one wholesale — the events you tick are the events the endpoint has, not events added to what it had before.

Event codes

share.downloaded and share.exploded are not event codes, despite appearing in some older notes. The set above is closed: naming a code outside it is refused when you create the subscription rather than stored and silently never fired.

user.emergency_expire is one event for the batch

Force-expiring an account's shares fires a single event carrying expired_count, not one event per share. That is deliberate: a per-share event would mean a delivery storm at exactly the moment somebody is dealing with an incident, and the individual short codes are not the useful part of that signal.

If you need to know which shares went, reconcile against your own records — the event tells you how many and when.

request.expired and request.deleted follow what happened to the request

The same two events come from the API and from the app. Each follows what actually happened to the request rather than what was asked for. Neither tells you what happened to its submissions, which depends on where the action was taken:

Both payloads carry only short_code. Do not read request.deleted as "the submissions are gone", or request.expired as "the submissions are safe". The emergency expire button in the app expires a user's active personal requests without either event; the action is reported by a single user.emergency_expire. See Expire or delete a request.

Who receives an event

Endpoints belong to an account, and an event goes to the endpoints of the account that owns the thing the event is about — not to whoever triggered it. So:

• Share events go to the share's owner, including share.viewed and share.access_denied, which are caused by a recipient.
• request.submitted goes to the request's owner, not to the person who submitted.
• org.member_added and org.member_removed go to the organization's owner.
• zk.team_key_granted goes to the admin who granted the key. The member who received it is not notified through webhooks.

The delivery payload

The body is a flat JSON object. event holds the event code; the remaining keys name the object involved, and are strings apart from the five noted in the field reference below. There is no wrapper object, and no id or timestamp inside the body — the delivery id and the event code arrive in the X-CredenShare-Delivery and X-CredenShare-Event headers.

Optional fields are omitted, not sent as null. Write your handler to treat a missing key as absent rather than expecting every key on every delivery.

Payloads are metadata only. No delivery ever carries shared content, a link fragment, a key, a passcode or an access token — see Payloads carry metadata only for why.

Fields by event

Fields marked ? are present only when they have a value.

The two organization events also differ from each other: org.member_added identifies the member by email, while org.member_removed identifies them by user_id. Read each one on its own terms.

Field reference

Most fields are JSON strings. Five are not, and they are marked below — a handler that coerces everything to a string will mangle expired_count, destructive, scopes, custody_level and custody_level_requested.

On request.submitted, short_code identifies the submission for the submissions endpoint. It is not a link: no route opens a submission by its short code.

Values of kind

kind names what was revoked. Today it is always device: the revocation behind this event deletes device envelopes only, so no other value can currently reach you. It is sent as an explicit statement rather than left implied, so a future envelope type does not change the meaning of a payload that never said which kind it meant.

Two properties worth coding against:

• Treat it as optional. It is read before the revocation, because afterwards the row is gone, and a failed lookup omits the field rather than blocking the revocation. Do not fail closed on its absence.
• Do not switch exhaustively on it. Handle device, and ignore values you do not recognise rather than erroring.

Values of reason

share.access_denied carries exactly one of these strings:

An unknown short code does not fire share.access_denied. That is deliberate: a wrong access token and a code that never existed look the same from the outside, so emitting on it would turn anyone guessing at short codes into a flood of notifications for you.

Example deliveries

A share created with a title, an expiry, and an owning organization. Values are illustrative:

{
  "event": "share.created",
  "short_code": "9kQ2vX7mB4",
  "title": "Staging database password",
  "organization_id": "4d1c9e2a-8b57-4f31-9a6e-2c0f7b8d1e34",
  "expired_at": "2026-09-03T17:00:00Z"
}

A refused read of that same share:

{
  "event": "share.access_denied",
  "short_code": "9kQ2vX7mB4",
  "reason": "Passcode does not match"
}

A submission to a secure request. short_code is the submitted share; secure_request_short_code is the request it answers:

{
  "event": "request.submitted",
  "short_code": "T4hL8sD1nW",
  "secure_request_short_code": "R7bK2mP9xQ",
  "title": "Response to: Onboarding credentials",
  "expired_at": "2026-09-10T14:22:11Z"
}

Handling unknown codes

The nineteen codes above are the whole set today, and you cannot subscribe to anything outside it. Still, write your handler so that a code it does not recognise is logged and acknowledged with a 2xx rather than treated as an error: a 4xx on an unrecognised event ends that delivery with no retry, and if the set is ever extended you would rather find out from your logs than from a gap.