# Sign-in hooks

A sign-in hook is an HTTPS endpoint you run. OhAuthCat calls it during each enterprise SSO sign-in, after every security check has passed and before the profile is issued, and your endpoint answers allow or deny, optionally adding claims. Sign-in hooks are a Business and Enterprise feature.

## Hook points

| Point                  | When                                                                                        | Your answer                |
| ---------------------- | ------------------------------------------------------------------------------------------- | -------------------------- |
| `pre_profile_issue`    | During the sign-in, synchronously                                                           | Allow or deny, plus claims |
| `post_directory_event` | After a directory change is stored, delivered by a background job with retries (8 attempts) | Ignored                    |

## Create a hook

`POST /v1/sign_in_hooks` (scope `policies:write`) with `point`, `url`, `timeout_ms` (default 2000, at most 5000) and `fail_mode`. The answer contains the signing secret once; `POST /v1/sign_in_hooks/{hook}/rotate_secret` replaces it. The CLI uses `ohauthcat sign-in-hooks`.

## The request

A signed JSON POST, verified the same way as [webhooks](/events/webhook-verification/), with an `OhAuthCat-Hook-Call-Id` header. The body has `call_id`, `point`, `created_at` and `sign_in`: the sign-in, environment, organization, connection and profile IDs, connection type, email, groups, role and, with a [risk policy](/signals/risk/), `risk_score` and `risk_reasons`.

## The answer

Answer `200` with a JSON body signed with the same secret, echoing the `call_id`: `decision` (`allow` or `deny`), an optional `reason` (up to 200 characters) and optional `claims`. Limits:

- the whole answer at most 8 KiB, with no redirects followed;
- at most 16 claims and 2 KiB in total; names are lowercase (`^[a-z][a-z0-9_]{0,39}$`), strings up to 256 characters, lists up to 16 items;
- profile fields and JWT claims (`email`, `sub`, `role`, `groups`, `exp` and the like) are reserved and cannot be set.

Claims appear in the profile under `claims`.

## When the hook fails

A timeout, a non-200 status, a bad signature, an answer for another call or an answer outside the limits is a failure. With `fail_mode: closed` (the default) the sign-in is refused with [`sign_in_hook_unavailable`](/errors/sign_in_hook_unavailable/); with `open` it continues without claims. A deny answers [`sign_in_hook_denied`](/errors/sign_in_hook_denied/). Every call appears as a `hook` step on the sign-in timeline.

## Delivery log and test events

- `GET /v1/sign_in_hooks/{hook}/deliveries` (scope `policies:read`) lists the hook's recent calls. For `pre_profile_issue` each row is a sign-in with its `outcome` (`allowed`, `denied`, `failed_open` or `failed_closed`), the HTTP status your endpoint answered and the latency. For `post_directory_event` each row is a delivery with its state (`pending`, `delivered` or `failed`) and attempts. Payloads are never kept.
- `POST /v1/sign_in_hooks/{hook}/test` (scope `policies:write`) sends a synthetic, signed request with `test: true` to your endpoint and shows the result. It does not appear in the delivery log; it is recorded in your audit log as `sign_in_hook.tested`.
