## Create an inbound webhook (comms:admin)

`POST /api/comms/v1/inbound-hooks`

Module: Comms · operationId: `createInboundHook` · Tag: Inbound webhooks · Auth: access token (`Authorization: Bearer <accessToken>`)

The answer carries the secret once; it cannot be read again, only rotated.

### Request body

`application/json` (required)

- `name` (string, required): Display name
- `config` (InboundConfig): Tunes the scheme to the sender; empty fields take the scheme's usual headers.
  - `idHeader` (string): Header with a unique delivery id; repeated ids are stored once
  - `prefix` (string): Text before the value, e.g. "sha256=" or "Bearer "
  - `signatureHeader` (string): Header with the signature (hmac_sha256) or the token (token)
- `enabled` (boolean): Disabled endpoints answer 404; omitted keeps the value (enabled on create)
- `maxBodyBytes` (integer): Largest accepted body (up to 1 MiB)
- `rev` (integer): Revision the change is based on (PATCH)
- `scheme` (string): How the sender is verified (one of `standard_webhooks`, `hmac_sha256`, `token`; default `"standard_webhooks"`)
- `toleranceSecs` (integer): Allowed clock difference for standard_webhooks (30–3600)

Example:

```json
{
  "config": {
    "idHeader": "X-Shop-Delivery",
    "prefix": "sha256=",
    "signatureHeader": "X-Shop-Signature"
  },
  "enabled": true,
  "maxBodyBytes": 262144,
  "name": "Shop-Bestellungen",
  "rev": 0,
  "scheme": "hmac_sha256"
}
```

### Responses

- **201** Endpoint with secret (`application/json`)
- **400** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 201 answer:

- `config` (InboundConfig): Tunes the scheme to the sender; empty fields take the scheme's usual headers.
  - `idHeader` (string): Header with a unique delivery id; repeated ids are stored once
  - `prefix` (string): Text before the value, e.g. "sha256=" or "Bearer "
  - `signatureHeader` (string): Header with the signature (hmac_sha256) or the token (token)
- `createdAt` (string (date-time)): Creation time
- `createdBy` (string): Who created the endpoint
- `enabled` (boolean): Disabled endpoints answer 404
- `id` (string (uuid)): Endpoint id
- `lastReceivedAt` (string (date-time)): Time of the last verified request
- `lastRejectedAt` (string (date-time)): Time of the last rejected request
- `lastRejectedReason` (string): Why the last request was rejected
- `maxBodyBytes` (integer): Largest accepted body in bytes
- `name` (string): Display name
- `receivedCount` (integer): Verified requests received
- `rejectedCount` (integer): Requests rejected by the check
- `rev` (integer): Revision for optimistic locking (send it back as `rev`)
- `scheme` (string): How the sender is verified
- `secret` (string): Only in the answer that created or rotated it
- `toleranceSecs` (integer): Allowed clock difference for standard_webhooks
- `url` (string): Public URL the sender posts to

Example 201 answer:

```json
{
  "config": {
    "idHeader": "X-Shop-Delivery",
    "prefix": "sha256=",
    "signatureHeader": "X-Shop-Signature"
  },
  "createdAt": "2026-10-01T10:20:00Z",
  "createdBy": "jonas.bauer@muster-it.example",
  "enabled": true,
  "id": "1a9e5c3b-7d2f-4e6a-b8c4-0d1e2f3a4b5c",
  "lastReceivedAt": "2026-11-18T07:55:32Z",
  "lastRejectedAt": "2026-11-02T13:10:04Z",
  "lastRejectedReason": "Signatur ungültig",
  "maxBodyBytes": 262144,
  "name": "Shop-Bestellungen",
  "receivedCount": 128,
  "rejectedCount": 2,
  "rev": 4,
  "scheme": "hmac_sha256",
  "toleranceSecs": 300,
  "url": "https://api.mbcom.cloud/api/comms/v1/hooks/f3Kq9ZpL2vXc8RtW1nYb4A"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/comms/v1/inbound-hooks' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"config":{"idHeader":"X-Shop-Delivery","prefix":"sha256=","signatureHeader":"X-Shop-Signature"},"enabled":true,"maxBodyBytes":262144,"name":"Shop-Bestellungen","rev":0,"scheme":"hmac_sha256"}'
```
