---
title: Hook kinds
description: "Every name that @jr2/orchestrator/hooks exports: the interface of a Hook kind, the kinds that jr2 ships, and webhook()."
---

# Hook kinds

`@jr2/orchestrator/hooks` is the interface of a [Hook kind](glossary.md#hook-kind), and the kinds that jr2 ships. `jr2.config.ts` imports a kind to declare a [Hook](glossary.md#hook), and a workflow module imports a kind's types for the handlers of a Gate slot or a Source. It is part of `@jr2/orchestrator`, so an Instance installs nothing more. A kind from another package has a peer dependency on `@jr2/orchestrator` and states `api: 1`. Each group of this page is one module that you import.

## Contents

- `@jr2/orchestrator/hooks`: [`HookRequest`](#type-hookrequest), [`Json`](#type-json), [`json`](#json), [`form`](#form), [`at`](#at), [`Signed`](#type-signed), [`Unsigned`](#type-unsigned), [`MacAlg`](#type-macalg), [`Verify`](#type-verify), [`HookSecret`](#type-hooksecret), [`CredentialOf`](#type-credentialof), [`HookCredential`](#type-hookcredential), [`Answer`](#type-answer), [`Handshake`](#type-handshake), [`Delivery`](#type-delivery), [`HookKindApi`](#type-hookkindapi), [`HOOK_KIND_APIS`](#hook-kind-apis), [`Events`](#type-events), [`HandlerKey`](#type-handlerkey), [`Named`](#type-named), [`Payloads`](#type-payloads), [`HookKind`](#type-hookkind), [`HookMay`](#type-hookmay), [`HookParts`](#type-hookparts), [`Hook`](#type-hook), [`HookKindOf`](#type-hookkindof), [`defineHookKind`](#definehookkind), [`HookKinds`](#type-hookkinds), [`EventsOf`](#type-eventsof), [`NoWildcardKeys`](#type-nowildcardkeys), [`PayloadOf`](#type-payloadof), [`KindHooks`](#type-kindhooks)
- `@jr2/orchestrator/hooks/github`: [`githubEvents`](#githubevents), [`github`](#github)
- `@jr2/orchestrator/hooks/gitlab`: [`gitlabEvents`](#gitlabevents), [`gitlab`](#gitlab)
- `@jr2/orchestrator/hooks/slack`: [`slackEvents`](#slackevents), [`slack`](#slack)
- `@jr2/orchestrator/hooks/discord`: [`discordEvents`](#discordevents), [`discord`](#discord)
- `@jr2/orchestrator/hooks/webhook`: [`Field`](#type-field), [`WebhookVerify`](#type-webhookverify), [`webhook`](#webhook)

## `@jr2/orchestrator/hooks`

The interface between the door of a Hook and a kind: `defineHookKind`, which makes a kind, the types of a kind, the helpers that read a request, and `HookKinds`, to which each kind adds its id and its payloads.

Each name in this group is declared in `@jr2/orchestrator/src/hook-kinds/index.ts`.

<a id="type-hookrequest"></a>

### `HookRequest`

Type.

```ts
type HookRequest = {
  readonly headers: { readonly [name: string]: string | undefined };
  readonly body: Uint8Array;
  readonly text: string;
};
```

One delivery, as the door got it. All of it is data. Header names are lowercase.

For a kind with a `token` verifier, `headers` does not hold the token's header: the door removes
it before it calls the kind. For `mac` and `ed25519`, no part of the request is secret: a
signature cannot make another signature.

**Fields**

- `headers`: `object`
- `body`: `Uint8Array`

  The raw body. A `mac` or `ed25519` signature covers these bytes.
- `text`: `string`

  The raw body as UTF-8.

<a id="type-json"></a>

### `Json`

Type.

```ts
type Json = null | boolean | number | string | readonly Json[] | { readonly [k: string]: Json };
```

A JSON value: what a kind puts in an answer.

<a id="json"></a>

### `json`

Function.

```ts
function json(req: HookRequest): unknown
```

The body as JSON. It throws when the body is not JSON. A throw from `read` is a 400, and the
hook log keeps the error.

**Parameters**

- `req` ([`HookRequest`](#type-hookrequest))

<a id="form"></a>

### `form`

Function.

```ts
function form(req: HookRequest): { readonly [field: string]: string | undefined }
```

The body as `application/x-www-form-urlencoded` fields. When a field occurs more than one time,
the first value is the field's value.

**Parameters**

- `req` ([`HookRequest`](#type-hookrequest))

<a id="at"></a>

### `at`

Function.

```ts
function at(value: unknown, path: string): unknown
```

The value at a dotted path (`sender.login`, `actions.0.action_id`) of a decoded body, or
`undefined`. It reads own properties only.

**Parameters**

- `value`
- `path`

<a id="type-signed"></a>

### `Signed`

Type.

```ts
type Signed = {
  readonly bytes: readonly (string | Uint8Array)[];
  readonly signature: { readonly hex: string } | { readonly base64: string };
  readonly at?: number;
};
```

What the service signed, from one request.

The door makes the checks. For `mac`, it first checks `at` against its clock, then sends the
bytes, the signature, the algorithm and the NAME of the Hook's secret to the Instance Effector,
which answers "match" or "no match" ([ADR-0068](decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)). For `ed25519`, it checks `at`, then the
signature against the Hook's public key, in the Orchestrator.

**Fields**

- `bytes`: `readonly (string | Uint8Array)[]`

  The bytes that the service signed, in sequence. The door joins them. A string is UTF-8.
  GitHub: `[req.body]`. Slack: `["v0:", timestamp, ":", req.body]`.
- `signature`: `{ readonly hex: string; } | { readonly base64: string; }`

  The signature, with no prefix (`sha256=`, `v0=`): the kind removes the prefix.
- `at` (optional): `number`

  The service's time of the delivery, in seconds since the epoch. Give it ONLY when the
  signature covers it (Slack, Discord). The door refuses a delivery whose `at` is more than
  300 s from its clock: 401. A kind cannot change the window.

<a id="type-unsigned"></a>

### `Unsigned`

Type.

```ts
type Unsigned = { readonly unsigned: string };
```

The request does not hold what the verifier needs. The door answers 401 and logs `unsigned`.

**Fields**

- `unsigned`: `string`

<a id="type-macalg"></a>

### `MacAlg`

Type.

```ts
type MacAlg = "sha256" | "sha1" | "sha512";
```

The HMAC algorithms that a `mac` verifier can name.

<a id="type-verify"></a>

### `Verify`

Type.

```ts
type Verify =
  | {
      readonly mac: {
        readonly alg: MacAlg;
        readonly signed: (req: HookRequest) => Signed | Unsigned;
      };
    }
  | { readonly ed25519: { readonly signed: (req: HookRequest) => Signed | Unsigned } }
  | { readonly token: { readonly header: string } };
```

How the service signs. One of three.

**Forms**: it is one of these objects.

- Form 1: `mac`

  - `mac`: `object`

    - `alg`: [`MacAlg`](#type-macalg)
    - `signed`: `(req: HookRequest) => Signed | Unsigned`
- Form 2: `ed25519`

  - `ed25519`: `object`

    - `signed`: `(req: HookRequest) => Signed | Unsigned`
- Form 3: `token`

  - `token`: `object`

    - `header`: `string`

<a id="type-hooksecret"></a>

### `HookSecret`

Type.

```ts
type HookSecret = { readonly secret: string };
```

A named secret: the value of `secret("NAME")` from `@jr2/orchestrator`. The config holds the
name only. The value is in the Instance Effector (`mac`), or its digest is in the Orchestrator
(`token`).

**Fields**

- `secret`: `string`

<a id="type-credentialof"></a>

### `CredentialOf`

Type.

```ts
type CredentialOf<V extends Verify> = V extends { readonly ed25519: unknown }
  ? { readonly publicKey: string }
  : { readonly secret: HookSecret };
```

What the Hook's config gives for each verifier. The kind never gets it.

<a id="type-hookcredential"></a>

### `HookCredential`

Type.

```ts
type HookCredential = { readonly secret: HookSecret } | { readonly publicKey: string };
```

The credential of a Hook, for each of the three verifiers.

**Forms**: it is one of these objects.

- Form 1: `secret`

  - `secret`: [`HookSecret`](#type-hooksecret)
- Form 2: `publicKey`

  - `publicKey`: `string`

<a id="type-answer"></a>

### `Answer`

Type.

```ts
type Answer = {
  readonly body: Json;
  readonly then?: { readonly post: `https://${string}`; readonly json: Json };
};
```

An answer that the kind writes. Its status is always 200: the door owns every other status.
`body`: an object or an array is JSON, a string is `text/plain`, `null` is an empty body.
`then`: one POST that the door makes AFTER the answer, through the Instance Effector's `http`,
with no secret, one time (the `response_url` of a Slack click). Its url must start with one of
the kind's `posts`. A failed post is a line in the hook log.

**Fields**

- `body`: [`Json`](#type-json)
- `then` (optional): `object`

  - `post`: `` `https://${string}` ``
  - `json`: [`Json`](#type-json)

<a id="type-handshake"></a>

### `Handshake`

Type.

```ts
type Handshake = { readonly handshake: Answer };
```

The service's handshake (Slack `url_verification`, Discord `PING`, GitHub `ping`). It comes
after the verifier and gets this answer. It reaches no handler, and the hook log keeps it as
`handshake`.

**Fields**

- `handshake`: [`Answer`](#type-answer)

<a id="type-delivery"></a>

### `Delivery`

Type.

```ts
type Delivery = {
  readonly key: string;
  readonly id: string;
  readonly payload: unknown;
  readonly onBehalfOf?: string;
  readonly readBy?: "service" | "person";
};
```

One delivery, which the door gives to the Gates and the Sources whose handlers hear its kind and
`key`. The kind's `events` gives the schema for each key. A key that `events` does not name is
still a delivery: the door does not parse it, and no handler can hear it, so it reaches nothing.

**Fields**

- `key`: `string`

  The event key. GitHub: `pull_request_review.submitted`.
- `id`: `string`

  The delivery id. The door's repeat check uses it AND the digest of the body.
- `payload`: `unknown`

  The decoded body. The signature covers it. The door parses it with the kind's schema for
  `key` (see `events`), and a handler gets the schema's output.
- `onBehalfOf` (optional): `string`

  The party that the service says acted. The signature covers it, so jr2 marks it checked.
- `readBy` (optional): `"service" | "person"`

  Who reads the answer. `"service"` (the default): the answer is the outcome JSON with the
  status that [ADR-0011](decisions/0011-workflow-defined-events.md) gives (429, 503). `"person"` (a chat command or a click): the door joins
  the `reply` texts, cuts them to `maxText`, and calls the kind's `answer`. The status is 200.

<a id="type-hookkindapi"></a>

### `HookKindApi`

Type.

```ts
type HookKindApi = 1;
```

The version of this interface. jr2 1.x calls each kind of `api: 1` as this module says.

<a id="hook-kind-apis"></a>

### `HOOK_KIND_APIS`

Constant.

```ts
const HOOK_KIND_APIS: readonly HookKindApi[]
```

The versions of the interface that this copy of `@jr2/orchestrator/hooks` knows.

<a id="type-events"></a>

### `Events`

Type.

```ts
type Events = { readonly [key: string]: z.ZodType };
```

The schema of each event key: `{ "pull_request_review.submitted": z.looseObject({ … }) }`.

- The door parses the payload of a delivery with the schema of its key, after the verifier and
  before the fan-out. A failed parse reaches no handler: the hook log keeps a `payload-refused`
  line with zod's issues, and the answer names the kind and the key. The status is 200, because
  a second try fails in the same way.
- Use `z.looseObject` for each object. A loose object keeps the fields that it does not name, so
  a new field from the service breaks nothing. A named field that is missing, or that has the
  wrong type, fails the parse. Name only the fields that handlers need. A value that the service
  can extend (a review's `state`) is a string, not an enum.
- A key that ends in `.*` is the schema of each key with that prefix: `"block_actions.*"` types
  `block_actions.approve` and `block_actions.reject`. An exact key comes first, then the longest
  prefix.

<a id="type-handlerkey"></a>

### `HandlerKey`

Type.

```ts
type HandlerKey<K> = K extends `${infer P}.*` ? `${P}.${string}` : K;
```

A key of `events` as a handler's key: `"block_actions.*"` → `` `block_actions.${string}` ``.

<a id="type-named"></a>

### `Named`

Type.

```ts
type Named<T> = T extends readonly unknown[]
  ? { readonly [I in keyof T]: Named<T[I]> }
  : T extends object
    ? { readonly [K in keyof T as string extends K ? never : K]: Named<T[K]> }
    : T;
```

The schema's output with only its named fields. The output of a loose object also has
`[field: string]: unknown`. The fields that it does not name stay in the value, but this type
removes the index signature, so a handler cannot read a field that its schema does not name.

<a id="type-payloads"></a>

### `Payloads`

Type.

```ts
type Payloads<E extends Events> = {
  readonly [K in keyof E & string as HandlerKey<K>]: Named<z.output<E[K]>>;
};
```

The payload type of each handler key of `events`.

<a id="type-hookkind"></a>

### `HookKind`

Type.

```ts
type HookKind<Id extends string = string, E extends Events = Events, V extends Verify = Verify> = {
  readonly api: HookKindApi;
  readonly id: Id;
  readonly events: E;
  readonly verify: V;
  readonly read: (req: HookRequest) => Handshake | Delivery;
  readonly answer?: (text: string, delivery: Delivery) => Answer;
  readonly maxText?: number;
  readonly posts?: readonly `https://${string}/`[];
};
```

A Hook kind: one outside service's protocol.

- `api`: the version of this interface that the kind was written for. Only `1` exists.
- `id`: the key of the `hooks` of a Gate or a Source. One id is one kind in an Assembly.
  Lowercase letters, digits and `-`, and it starts with a letter.
- `events`: a zod schema for each event key that a handler can hear ([`Events`](#type-events)).
- `verify`: one of the three verifiers, and what the service signed.
- `read`: the verified request, as a handshake or a delivery. A throw is 400, and the hook log
  keeps the error.
- `answer`: the envelope of the text for a delivery with `readBy: "person"`. The door gives the
  joined text, already cut to `maxText`. The kind escapes it. A kind with no `answer` cannot give
  `readBy: "person"`: the type of `read` refuses it ([`defineHookKind`](#definehookkind)).
- `maxText`: the service's limit on the length of the text (Discord: 2000).
- `posts`: the url prefixes of `Answer.then`. `jr2 up` adds them to the Instance Effector's fence
  for each Hook of this kind ([ADR-0068](decisions/0068-an-effector-holds-an-effects-secrets-and-signs-its-wire.md)). The door refuses a `then` to another url.

**Fields**

- `api`: [`HookKindApi`](#type-hookkindapi)
- `id`: `Id`
- `events`: `E`
- `verify`: `V`
- `read`: `(req: HookRequest) => Handshake | Delivery`
- `answer` (optional): `(text: string, delivery: Delivery) => Answer`
- `maxText` (optional): `number`
- `posts` (optional): ``readonly `https://${string}/`[]``

<a id="type-hookmay"></a>

### `HookMay`

Type.

```ts
type HookMay = { readonly answer: "all" | readonly string[] };
```

The Workflows whose Gates a Hook may answer ([ADR-0078](decisions/0078-a-caller-comes-from-one-authenticator-seam-and-acts-within-its-scopes.md)). The default is `"all"`. A Hook never
starts a run.

**Fields**

- `answer`: `"all" | readonly string[]`

<a id="type-hookparts"></a>

### `HookParts`

Type.

```ts
type HookParts<K extends HookKind = HookKind> = {
  readonly kind: K;
  readonly credential: HookCredential;
  readonly may: HookMay;
};
```

The parts of a Hook, which only the door reads.

**Fields**

- `kind`: `K`
- `credential`: [`HookCredential`](#type-hookcredential)
- `may`: [`HookMay`](#type-hookmay)

<a id="type-hook"></a>

### `Hook`

Type.

```ts
type Hook<K extends HookKind = HookKind> = { readonly [HOOK]: HookParts<K> };
```

A Hook: a kind, a credential and `may`. It is the value of one entry of `hooks` in
`jr2.config.ts`, and the entry's key is its name, the last segment of `POST /hooks/:name`. Only
the door reads it.

**Fields**

- `[HOOK]`: `HookParts<K>`

<a id="type-hookkindof"></a>

### `HookKindOf`

Type.

```ts
type HookKindOf<Id extends string, E extends Events, V extends Verify> = HookKind<Id, E, V> &
  ((hook: CredentialOf<V> & { readonly may?: HookMay }) => Hook<HookKind<Id, E, V>>);
```

A kind is also the constructor of its Hooks: `github({ secret: secret("GH_HOOK"), may })`.

<a id="definehookkind"></a>

### `defineHookKind`

Function.

#### Overload 1

```ts
function defineHookKind<
  const Id extends string,
  const E extends Events,
  const V extends Verify,
>(
  kind: HookKind<Id, E, V> & { readonly answer: NonNullable<HookKind["answer"]> },
): HookKindOf<Id, E, V>
```

Define a kind. jr2 makes the constructor, so the credential goes from the config to the door and
never through code of the kind.

It throws on an `api` that it does not know, an `id` that is not lowercase, an `events` entry
that is not a schema, a verifier that is not one of the three, a `posts` entry that is not an
`https://` url that ends in `/`, and a `maxText` that is not a positive integer. Two different
kinds with one `id` fail the typecheck (`HookKinds`) and `jr2 up`.

Two overloads: a kind with `answer` can give `readBy: "person"`; a kind with no `answer` cannot.

**Parameters**

- `kind`

  - `api`: [`HookKindApi`](#type-hookkindapi)
  - `id`: `Id`
  - `events`: `E`
  - `verify`: `V`
  - `read`: `(req: HookRequest) => Handshake | Delivery`
  - `answer`: `(text: string, delivery: Delivery) => Answer`
  - `maxText` (optional): `number`
  - `posts` (optional): ``readonly `https://${string}/`[]``

#### Overload 2

```ts
function defineHookKind<
  const Id extends string,
  const E extends Events,
  const V extends Verify,
>(
  kind: Omit<HookKind<Id, E, V>, "read" | "answer" | "maxText" | "posts"> & {
    readonly read: (req: HookRequest) => Handshake | (Delivery & { readonly readBy?: "service" });
  },
): HookKindOf<Id, E, V>
```

**Parameters**

- `kind`

  - `id`: `Id`
  - `api`: [`HookKindApi`](#type-hookkindapi)
  - `events`: `E`
  - `verify`: `V`
  - `read`: `(req: HookRequest) => Handshake | (Delivery & { readonly readBy?: "service"; })`

<a id="type-hookkinds"></a>

### `HookKinds`

Type.

#### Overload 1

```ts
interface HookKinds {}
```

Each kind module adds its id and its kind here by declaration merging.

#### Overload 2

```ts
interface HookKinds {
    github: typeof github;
  }
```

**Fields**

- `github`: `typeof github`

#### Overload 3

```ts
interface HookKinds {
    gitlab: typeof gitlab;
  }
```

**Fields**

- `gitlab`: `typeof gitlab`

#### Overload 4

```ts
interface HookKinds {
    slack: typeof slack;
  }
```

**Fields**

- `slack`: `typeof slack`

#### Overload 5

```ts
interface HookKinds {
    discord: typeof discord;
  }
```

**Fields**

- `discord`: `typeof discord`

<a id="type-eventsof"></a>

### `EventsOf`

Type.

```ts
type EventsOf<K> = K extends HookKind<string, infer E, Verify> ? Payloads<E> : never;
```

The payload map of a kind: handler key → the output of its schema.

<a id="type-nowildcardkeys"></a>

### `NoWildcardKeys`

Type.

```ts
type NoWildcardKeys<K> =
  K extends HookKind<string, infer E, Verify>
    ? { readonly [Key in keyof E & string as Key extends `${string}*${string}` ? Key : never]?: never }
    : never;
```

A kind's `events` keys with `*`, which take no handler: the door matches a key exactly ([ADR-0011](decisions/0011-workflow-defined-events.md)).

<a id="type-payloadof"></a>

### `PayloadOf`

Type.

```ts
type PayloadOf<Id extends keyof HookKinds, Key extends keyof EventsOf<HookKinds[Id]>> = EventsOf<
  HookKinds[Id]
>[Key];
```

The payload of one handler key of a kind in `HookKinds`: `PayloadOf<"github", "issue_comment.created">`.
A forge part types its handlers with it.

<a id="type-kindhooks"></a>

### `KindHooks`

Type.

```ts
type KindHooks<In, Out> = {
  readonly [Id in keyof HookKinds as HookKinds[Id] extends { readonly id: Id } ? Id : never]?: {
    readonly [Key in keyof EventsOf<HookKinds[Id]>]?: (
      d: In & { readonly payload: EventsOf<HookKinds[Id]>[Key] },
    ) => Out;
  } & NoWildcardKeys<HookKinds[Id]>;
};
```

Handlers by kind id, then by event key. An entry of `HookKinds` whose key is not its kind's `id`
is left out, so no handler is keyed by a name that the door never matches. `In` is what the Gate
or the Source gives a handler beside `payload`; `Out` is what the handler gives. A key that the
kind's payloads do not name is an excess property: it does not compile. A key that holds `*`
does not compile ([`NoWildcardKeys`](#type-nowildcardkeys)).

**Fields**

- `github` (optional): `typeof github`
- `gitlab` (optional): `typeof gitlab`
- `slack` (optional): `typeof slack`
- `discord` (optional): `typeof discord`

## `@jr2/orchestrator/hooks/github`

The kind of GitHub. It verifies with `mac`, over the raw body.

Each name in this group is declared in `@jr2/orchestrator/src/hook-kinds/github.ts`.

<a id="githubevents"></a>

### `githubEvents`

Constant.

```ts
const githubEvents: { "pull_request_review.submitted": …; "issue_comment.created": …; "check_suite.completed": … }
```

The schema of each event key. Each names only the fields that handlers read; a loose object keeps
the rest. A value that GitHub can extend (a review's `state`) is a string, not an enum, so a new
value fails no parse.

<a id="github"></a>

### `github`

Constant.

```ts
const github: HookKindOf<…>
```

Type: [`HookKindOf`](#type-hookkindof).

A GitHub repository, organization or App webhook, with the content type `application/json`. (A
webhook with the content type `application/x-www-form-urlencoded` gets 400.)
- verifier: `mac`, HMAC-SHA256 of the raw body, `X-Hub-Signature-256: sha256=<hex>`.
- handshake: the `ping` event (sent when the webhook is made) gets an empty 200.
- event key: `<X-GitHub-Event>.<action>`, or `<X-GitHub-Event>` when the body has no action.
- delivery id: `X-GitHub-Delivery`. `onBehalfOf`: `sender.login`.
- answer: the outcome (the default). No person reads it.

## `@jr2/orchestrator/hooks/gitlab`

The kind of GitLab. It verifies with `token`, in the header `X-Gitlab-Token`.

Each name in this group is declared in `@jr2/orchestrator/src/hook-kinds/gitlab.ts`.

<a id="gitlabevents"></a>

### `gitlabEvents`

Constant.

```ts
const gitlabEvents: { "merge_request.approved": …; "note.MergeRequest": …; "pipeline.success": …; "pipeline.failed": … }
```

The schema of each event key: the fields that handlers read, in loose objects.

<a id="gitlab"></a>

### `gitlab`

Constant.

```ts
const gitlab: HookKindOf<…>
```

Type: [`HookKindOf`](#type-hookkindof).

A GitLab project or group webhook.
- verifier: `token`, the secret token in `X-Gitlab-Token`.
- handshake: none. A "Test" delivery from GitLab's settings is an ordinary delivery.
- event key: `<object_kind>.<the second part>`, or `<object_kind>` when it has no second part.
  The second part is `object_attributes.noteable_type` for a `note`, and else
  `object_attributes.action`, then `object_attributes.status`: `merge_request.approved`,
  `note.MergeRequest`, `pipeline.success`.
- delivery id: `Idempotency-Key` (the same on a retry), else `X-Gitlab-Event-UUID`. (From
  GitLab's docs; not checked against a real delivery.)
- `onBehalfOf`: `user.username`.
- answer: the outcome (the default). No person reads it.

## `@jr2/orchestrator/hooks/slack`

The kind of one Slack app: its slash commands, its clicks and its Events API. It verifies with `mac`, over the signed time and the body.

Each name in this group is declared in `@jr2/orchestrator/src/hook-kinds/slack.ts`.

<a id="slackevents"></a>

### `slackEvents`

Constant.

```ts
const slackEvents: { "slash_command.*": …; "block_actions.*": …; "event_callback.app_mention": … }
```

The schema of each event key. A key with `.*` covers a family: the command or the action id is
part of the key, so one schema types `block_actions.approve` and `block_actions.reject`.

<a id="slack"></a>

### `slack`

Constant.

```ts
const slack: HookKindOf<…>
```

Type: [`HookKindOf`](#type-hookkindof).

- verifier: `mac`, HMAC-SHA256 of `v0:<X-Slack-Request-Timestamp>:<raw body>`,
  `X-Slack-Signature: v0=<hex>`. The signature covers the timestamp, so the kind gives it as
  `at`, and the door's 300 s window applies (Slack asks for 5 minutes).
- handshake: `url_verification` gets `{ challenge }`. The door verifies it first. (Slack's docs
  do not say that Slack signs it; check it at the first real setup.)
- body: a command is a form; a click is a form with JSON in `payload`; an event is JSON.
- event keys: `slash_command./jr2`, `block_actions.<action_id>`, `event_callback.<event.type>`.
- delivery id: `event_id` for an event, `trigger_id` for a command or a click. (Slack's docs do
  not say that a `trigger_id` is unique for each request; the door's repeat check also uses the
  digest of the body.)
- `onBehalfOf`: the Slack user id, never a display name.
- who reads the answer: a person for a command or a click; Slack for an event (so a 503 stays a
  503, and Slack sends the event again).
- answer: ephemeral text. The answer to a click can only be an empty 200 (Block Kit), so the text
  goes to the click's `response_url` as the answer's `then`.
- text limit: 4000 characters, the length that Slack's docs advise for a message's `text`. (Not
  checked for the answer to a command or a `response_url` post.)

## `@jr2/orchestrator/hooks/discord`

The kind of a Discord application's Interactions Endpoint URL. It verifies with `ed25519`, over the signed time and the body.

Each name in this group is declared in `@jr2/orchestrator/src/hook-kinds/discord.ts`.

<a id="discordevents"></a>

### `discordEvents`

Constant.

```ts
const discordEvents: { "application_command.*": …; message_component: … }
```

The schema of each event key. A command's name is part of its key, so `.*` covers them all.

<a id="discord"></a>

### `discord`

Constant.

```ts
const discord: HookKindOf<…>
```

Type: [`HookKindOf`](#type-hookkindof).

- verifier: `ed25519` over `<X-Signature-Timestamp><raw body>`, `X-Signature-Ed25519` in hex,
  checked against the application's PUBLIC key in the Orchestrator. The signature covers the
  timestamp, so the kind gives it as `at`. Discord states no window; the door's 300 s window
  applies to each signed `at`, so it applies here too.
- handshake: `PING` (type 1) gets `{ type: 1 }` (PONG).
- event keys: `application_command.<data.name>` (type 2), `message_component` (type 3). Another
  type (an autocomplete, a modal) gets the key `interaction.<type>`, which has no schema, so it
  reaches nothing.
- delivery id: the interaction's `id`. `onBehalfOf`: `member.user.id`, or `user.id` in a direct
  message. (Discord's docs do not say that Discord sends an interaction again.)
- who reads the answer: a person, always.
- answer: `{ type: 4, data: { content, flags: 64 } }`, an ephemeral message. Discord shows
  markdown, not HTML, so the text needs no escape. Text limit: 2000 characters.

## `@jr2/orchestrator/hooks/webhook`

`webhook()` makes a kind from data, for a service that has no kind: a verifier over the raw body, the event key, the delivery id, `onBehalfOf`, and a schema for each event.

Each name in this group is declared in `@jr2/orchestrator/src/hook-kinds/webhook.ts`.

<a id="type-field"></a>

### `Field`

Type.

```ts
type Field = { readonly header: string } | { readonly json: string };
```

Where a value is in a delivery: a header (lowercase), or a dotted path in the JSON body.

**Forms**: it is one of these objects.

- Form 1: `header`

  - `header`: `string`
- Form 2: `json`

  - `json`: `string`

<a id="type-webhookverify"></a>

### `WebhookVerify`

Type.

```ts
type WebhookVerify =
  | {
      readonly mac: {
        readonly header: string;
        readonly alg?: MacAlg;
        readonly prefix?: string;
        readonly encoding?: "hex" | "base64";
      };
    }
  | { readonly token: { readonly header: string } };
```

How the general kind verifies. `mac` is over the raw body only.

**Forms**: it is one of these objects.

- Form 1: `mac`

  - `mac`: `object`

    - `header`: `string`

      The header of the signature (lowercase).
    - `alg` (optional): [`MacAlg`](#type-macalg)

      `sha256` when it is not given.
    - `prefix` (optional): `string`

      The text before the signature in the header's value, such as `sha256=`.
    - `encoding` (optional): `"hex" | "base64"`

      `hex` when it is not given.
- Form 2: `token`

  - `token`: `object`

    - `header`: `string`

<a id="webhook"></a>

### `webhook`

Function.

```ts
function webhook<
  const Id extends string,
  const E extends Events,
  const W extends WebhookVerify,
>(
  spec: {
    readonly id: Id;
    readonly events: E;
    readonly verify: W;
    readonly key: Field | { readonly name: Field; readonly action?: Field };
    readonly delivery: Field;
    readonly onBehalfOf?: Field;
  },
): HookKindOf<Id, E, VerifyOf<W>>
```

A kind from data.
- `id`: the kind's id. The Instance chooses it; it must not be the id of another kind.
- `events`: a zod schema for each event key that a handler can hear. The door parses with it, as
  for each kind (`Events` in `@jr2/orchestrator/hooks`).
- `verify`: `mac` over the raw body (the header, its prefix, the algorithm, the encoding), or
  `token` in a header.
- `key`: the event key, from one field; or `{ name, action }`, which gives `<name>.<action>`, or
  `<name>` when the delivery has no action.
- `delivery`: the delivery id. `onBehalfOf`: optional.

The answer is the outcome JSON.

**Parameters**

- `spec`

  - `id`: `Id`
  - `events`: `E`
  - `verify`: `W`
  - `key`: `Field | { readonly name: Field; readonly action?: Field; }`
  - `delivery`: [`Field`](#type-field)
  - `onBehalfOf` (optional): [`Field`](#type-field)

## Types these signatures name

A signature above names these types, or a type here names them. They are not exports of `@jr2/orchestrator`, so a workflow module does not import them by name. With them, each kit type that this page shows has a definition on a Reference page.

<a id="type-verifyof"></a>

### `VerifyOf`

```ts
type VerifyOf<W extends WebhookVerify> = W extends { readonly mac: unknown }
  ? Extract<Verify, { readonly mac: unknown }>
  : Extract<Verify, { readonly token: unknown }>;
```

These names come from a dependency:

- `z.ZodType`: from `zod`
- `z.output`: from `zod`
