---
title: "Set the inbox webhook: an HMAC-signed POST for every inbound message"
method: PUT
path: "/api/v1/inboxes/{inboxId}/webhook"
tags: ["Inboxes"]
---

# Set the inbox webhook: an HMAC-signed POST for every inbound message

`PUT /api/v1/inboxes/{inboxId}/webhook`

## Request

- Base URL: `https://machineinbox.com`
- URL: `https://machineinbox.com/api/v1/inboxes/{inboxId}/webhook`
- Auth: none required

Registers one https webhook per inbox. Each inbound message triggers a signed POST carrying metadata, the extracted verification code and links, and the injection-risk scan - never the message body (fetch content with the mailbox token). Verify X-MachineInbox-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>"> using the returned secret; reject timestamps older than five minutes. Failed deliveries retry with backoff; after 20 consecutive failures the webhook is disabled until the next PUT.

## Path parameters

- `inboxId` string, uuid, required

## Request body

- SetWebhookRequest
  - `url` string, uri, required: Public https URL. Private addresses, IP literals, and this service's own hosts are rejected.

## Response `200`

Webhook stored. The derived signing secret is returned on every PUT.

- SetWebhookResponse
  - `webhook` Webhook, required
    - `url` string, uri, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `lastSuccessAt` string, date-time, nullable, required
    - `lastFailureAt` string, date-time, nullable, required
    - `lastFailureReason` string, nullable, required
    - `consecutiveFailures` integer, required
    - `disabled` boolean, required
  - `secret` string, required: HMAC-SHA256 signing secret for X-MachineInbox-Signature. Returned on every PUT; never shown elsewhere.
  - `secretNotice` string, required

## Other responses

- `400`: The request is malformed.
- `401`: A valid mailbox bearer token is required.
- `403`: The inbox is suspended.
- `404`: The inbox, message, attachment, or route was not found.
- `410`: The inbox has expired.
- `429`: A request or reply limit was reached.

---

[API](https://skmtc.dev/machineinbox/apis/machine-inbox-api.md) · [All operations](https://skmtc.dev/machineinbox/apis/machine-inbox-api/llms.txt) · [OpenAPI document](https://skmtc.dev/machineinbox/apis/machine-inbox-api/revisions/bcb3cf08ad6d?raw)