> ## Documentation Index
> Fetch the complete documentation index at: https://inkbox.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Inbound

> Create Inbound sources that receive third-party webhooks for a hosted agent, rotate their URLs, and list or replay received events.

Paths are relative to `https://inkbox.ai/api/v1/identities/my-agent`. Authenticate with an API key in `X-API-Key`. Admin-scoped keys and the identity's own claimed agent-scoped key can use these endpoints. In the Console, any organization member can view sources (including their URLs) and events, create sources the agent handles, and rename, re-sign, rotate or delete them. Creating, editing, rotating or deleting a script source, switching a source to or from a script handler, and replaying events need an organization owner or admin.

Creating, updating, and rotating sources and replaying events need a [hosted agent](https://inkbox.ai/docs/capabilities/hosted-agents.md); otherwise they return `409` with code `identity_not_hosted`. [Removing hosting](https://inkbox.ai/docs/api/identities/hosting.md#remove-hosting) deletes the agent's sources and their events. Their URLs stop working as soon as removal starts. For concepts and setup guides, see [Inbound](https://inkbox.ai/docs/capabilities/inbound.md).

## Source

```json theme={null}
{
  "id": "inbsrc_3d9a7c21-6e4f-4b8a-9d2c-1f5e8a7b0c34",
  "name": "stripe",
  "url": "https://my-agent.inkbox.sh/inbound/k3Jx9...",
  "signature": {"secret_encoding": "text", "header": "Stripe-Signature", "format": "list", "format_value": "v1", "algorithm": "sha256", "encoding": "hex", "signed_content": "{timestamp}.{body}", "timestamp_from": "list", "timestamp_value": "t", "max_age_seconds": 300},
  "handler": {"type": "agent", "instructions": "Summarize failed payments and email the account owner."},
  "created_at": "2026-11-20T15:00:00Z",
  "updated_at": "2026-11-20T15:00:00Z"
}
```

| Field | Meaning |
| - | - |
| `id` | Source ID, prefixed `inbsrc_`. |
| `name` | Label shown to the agent with each event. |
| `url` | URL to give the sender. Anyone with it can send events. |
| `signature` | [Signature settings](https://inkbox.ai/docs/capabilities/inbound.md#signature-settings) with every field filled in, or `null`. Never includes the secret. |
| `handler` | `{"type": "agent", "instructions"?}` or `{"type": "script", "command"}`. |

## Create a source

`POST /inbound`

```json theme={null}
{
  "name": "stripe",
  "signature": {"secret": "whsec_...", "header": "Stripe-Signature", "format": "list", "format_value": "v1", "signed_content": "{timestamp}.{body}", "timestamp_from": "list", "timestamp_value": "t", "max_age_seconds": 300},
  "handler": {"type": "agent", "instructions": "Summarize failed payments and email the account owner."}
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | 1 to 64 characters. |
| `signature` | object \| null | No | Signing secret settings. Omit or send `null` to rely on the URL token alone. |
| `signature.secret` | string | Yes | Secret from the sender. Up to 1,024 characters. Write-only. |
| `signature.secret_encoding` | string | No | `text` (default) or `base64`. `base64` ignores a leading `whsec_` and must decode. |
| `signature.header` | string | Yes | Signature header. Letters, digits, and hyphens; up to 128 characters. |
| `signature.format` | string | No | `whole` (default), `prefix`, or `list`. |
| `signature.format_value` | string | `prefix` and `list` | The prefix, or the list key. Up to 32 characters. A list key uses letters, digits, `_`, `.`, and `-`. Not allowed with `whole`. |
| `signature.algorithm` | string | No | `sha256` (default), `sha1`, or `sha512`. |
| `signature.encoding` | string | No | `hex` (default) or `base64`. |
| `signature.signed_content` | string | No | Template of what was signed. Defaults to `{body}`. Must include `{body}` exactly once; may use `{timestamp}`, `{header:Name}`, and literal text without braces. Up to 256 characters. |
| `signature.timestamp_from` | string | No | `none` (default), `header`, or `list`. Required when `signed_content` uses `{timestamp}` or `max_age_seconds` is set. `list` needs `format: "list"`. |
| `signature.timestamp_value` | string | With `timestamp_from` | The timestamp header name, or its list key. |
| `signature.max_age_seconds` | integer | No | 1 to 604,800. Rejects requests whose timestamp is further than this from now. Requires the timestamp to be signed: `{timestamp}` in `signed_content`, or `{header:<timestamp header>}` when `timestamp_from` is `header`. |
| `handler` | object | No | Defaults to `{"type": "agent"}`. |
| `handler.instructions` | string | No | `agent` only: up to 4,000 characters. |
| `handler.command` | string | `script` only | Shell command to run on the agent's computer. Up to 4,000 characters. |

Returns `201` with the source. Invalid signature settings return `422` with the reason. An agent can have up to 50 sources; creating another returns `409` with code `inbound_source_limit`.

See [example settings](https://inkbox.ai/docs/capabilities/inbound.md#example-settings) for common senders.

## List sources

`GET /inbound`

Returns `{"sources": [Source]}`, oldest first.

## Get a source

`GET /inbound/{source_id}`

## Update a source

`PATCH /inbound/{source_id}`

Send any of `name`, `signature`, and `handler`. Omitted fields keep their values. Send `"signature": null` to remove verification. A new `signature` replaces the old one and needs its `secret`. The URL doesn't change.

## Delete a source

`DELETE /inbound/{source_id}`

Deletes the source and all of its events. Its URL stops working. Returns `204`.

## Rotate a source URL

`POST /inbound/{source_id}/rotate`

Returns the source with a new `url`. The old URL stops working immediately.

## Check a signature

`POST /inbound/signature-check`

Checks a sample request against signature settings, or against a saved source's settings and secret. Nothing is stored.

```json theme={null}
{
  "signature": {"secret": "example-secret", "header": "X-Hub-Signature-256", "format": "prefix", "format_value": "sha256="},
  "headers": {"X-Hub-Signature-256": "sha256=017b01d4fc0b52a5886692e193d45f6e406b395c6e43aa20fa5f2809b566c15f"},
  "body": "Hello, World!"
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `signature` | object | One of `signature` or `source_id` | Settings to check, as in [Create a source](#create-a-source), including `secret`. |
| `source_id` | string | One of `signature` or `source_id` | Check against this source's saved settings and secret instead. |
| `headers` | object | Yes | The sample request's headers. Up to 100. |
| `body` | string | Yes | The sample request's raw body, exactly as sent. |
| `body_encoding` | string | No | `utf8` (default) or `base64` for a body that isn't text. |

This sample is signed with `example-secret`, so it returns `200` with:

```json theme={null}
{"verified": true, "reason": null}
```

When the signature doesn't match, `verified` is `false` and `reason` says why, such as `"Signature does not match"`. A timestamped sample older than `max_age_seconds` fails with a timestamp reason, so use a recent request.

## Event

```json theme={null}
{
  "id": "inbev_8c1f2e47-9a3b-4d6e-b5c0-2f7a1d9e4b63",
  "source_id": "inbsrc_3d9a7c21-6e4f-4b8a-9d2c-1f5e8a7b0c34",
  "received_at": "2026-11-20T15:04:05Z",
  "status": "delivered",
  "attempts": 1,
  "last_error": null,
  "signature_verified": true,
  "content_type": "application/json",
  "size_bytes": 2048
}
```

| Field | Meaning |
| - | - |
| `status` | `pending`, `delivered`, or `failed`. |
| `attempts` | Delivery attempts so far. |
| `last_error` | Last delivery error code or handler error, or `null`. |
| `signature_verified` | `true` when the signature was checked and matched. |

## List events

`GET /inbound/{source_id}/events`

| Query | Description |
| - | - |
| `limit` | 1 to 100. Defaults to 50. |
| `cursor` | `next_cursor` from the previous page. |

Returns `{"events": [Event], "next_cursor": "inbev_..." | null}`, newest first.

## Get an event

`GET /inbound/{source_id}/events/{event_id}`

Returns the event plus `request`, the request as received:

```json theme={null}
{
  "request": {
    "method": "POST",
    "query": {},
    "headers": {"content-type": "application/json", "stripe-signature": "t=...,v1=..."},
    "content_type": "application/json",
    "body": "{\"id\":\"evt_...\"}",
    "body_encoding": "utf8"
  }
}
```

`body_encoding` is `utf8` for bodies that are valid UTF-8 and `base64` otherwise. Decode `body` by `body_encoding`, not by `content_type`. Credentials and connection headers aren't stored.

## Replay an event

`POST /inbound/{source_id}/events/{event_id}/replay`

Delivers the event to the agent again with a new `delivery_id` and resets its `status` to `pending`. Returns `202` with the event.

## Report a failed event

`POST /inbound/{source_id}/events/{event_id}/result`

The agent reports an event it couldn't handle, so you can find and replay it. Requires the identity's own agent-scoped key.

```json theme={null}
{"status": "failed", "error": "Script exited with status 1", "delivery_id": "6f0c2a8e-..."}
```

| Field | Description |
| - | - |
| `status` | `failed`. |
| `error` | Up to 2,000 characters; Inkbox keeps the last 255. |
| `delivery_id` | `data.delivery_id` from the [`inbound.received`](https://inkbox.ai/docs/capabilities/inbound#the-inbound-received-event) payload being reported. |

Returns `204`. If the event was replayed since that delivery, returns `409` with code `stale_delivery` and changes nothing; treat that as done.

## Receive events

Senders post to the source's `url`. See [responses to the sender](https://inkbox.ai/docs/capabilities/inbound.md#responses-to-the-sender) and the [`inbound.received` payload](https://inkbox.ai/docs/capabilities/inbound#the-inbound-received-event).

## SDKs

| Operation | Python (`client.inbound`) | TypeScript (`inkbox.inbound`) |
| - | - | - |
| Create | `create_source` | `createSource` |
| List | `list_sources` | `listSources` |
| Get | `get_source` | `getSource` |
| Update | `update_source` | `updateSource` |
| Delete | `delete_source` | `deleteSource` |
| Rotate URL | `rotate_source` | `rotateSource` |
| Check a signature | `check_signature` | `checkSignature` |
| List events | `list_events` | `listEvents` |
| Get event | `get_event` | `getEvent` |
| Replay | `replay_event` | `replayEvent` |
| Report failure | `report_inbound_event_result(..., delivery_id=...)` | `reportInboundEventResult(..., { deliveryId })` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.