> ## 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

> Receive webhooks from Stripe, GitHub, and other services on a hosted agent. Inkbox verifies, stores, and delivers them, even while the agent sleeps.

Inbound lets other services send webhooks to your [hosted agent](https://inkbox.ai/docs/capabilities/hosted-agents.md). Point Stripe, GitHub, a form builder, or your own app at an Inbound URL. Inkbox checks the request, stores it, and responds right away. It then delivers the event, waking the agent's computer if it is asleep or starting it if it is stopped, whether it stopped after being idle or you stopped it.

The sender never waits for the agent.

Inbound is the opposite direction of [Webhooks](https://inkbox.ai/docs/webhooks.md). Webhooks send Inkbox events to your servers. Inbound brings other services' events to your hosted agent.

Inbound is available on hosted agents only.

## Sources

A source is one URL for one sender. Create a source for each service you connect. Each source has:

* **Name.** A label such as `stripe` or `github`. The agent sees it with every event.
* **URL.** `https://my-agent.inkbox.sh/inbound/...`, with a random token at the end.
* **Signature settings.** Optional. Inkbox verifies the sender's HMAC signature with the sender's secret.
* **Handler.** What happens when an event arrives: the agent handles it, or a script on the agent's computer does.

Create a source with the [Inbound API](https://inkbox.ai/docs/api/identities/inbound.md#create-a-source):

```bash theme={null}
curl -X POST https://inkbox.ai/api/v1/identities/my-agent/inbound \
  -H "X-API-Key: $INKBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"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."}}'
```

The response includes the `url` to give the sender.

With the Python SDK:

```python theme={null}
source = client.inbound.create_source(
    "my-agent",
    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."},
)
print(source.url)
```

In TypeScript, the same resource is `inkbox.inbound` with `createSource`, `listSources`, `getSource`, `updateSource`, `deleteSource`, `rotateSource`, `checkSignature`, `listEvents`, `getEvent`, and `replayEvent`. TypeScript signature fields are camelCase: `formatValue`, `signedContent`, `timestampFrom`, `timestampValue`, `maxAgeSeconds`, and `secretEncoding`.

With the CLI, pass the signing secret on stdin so it stays out of your shell history:

```bash theme={null}
printf %s "$STRIPE_WEBHOOK_SECRET" | inkbox inbound create my-agent --name stripe --secret-stdin \
  --header Stripe-Signature --format list --format-value v1 --signed-content '{timestamp}.{body}' \
  --timestamp-from list --timestamp-value t --max-age 300
inkbox inbound list my-agent
inkbox inbound rotate my-agent <source-id>
inkbox inbound events list my-agent <source-id>
inkbox inbound events replay my-agent <source-id> <event-id>
```

The CLI also has `inbound get`, `inbound update`, `inbound delete`, `inbound check-signature`, and `inbound events get`. Use `--handler script --command "<command>"` for a script handler. The signature flags match the [signature fields](#signature-settings): `--header`, `--secret-encoding`, `--format`, `--format-value`, `--algorithm`, `--encoding`, `--signed-content`, `--timestamp-from`, `--timestamp-value`, and `--max-age`.

An agent can have up to 50 sources.

## URL token

The token in the URL is a secret. Anyone with the URL can send events to the source. Without a signing secret, the token is the only check.

If a URL leaks, [rotate it](https://inkbox.ai/docs/api/identities/inbound.md#rotate-a-source-url). The old URL stops working immediately. Update the sender with the new URL.

## Signing secrets

Most services sign their webhooks with an HMAC of the request. Describe how your sender signs, add its signing secret, and Inkbox rejects requests without a valid signature with `401`. The secret is write-only: Inkbox never returns it. Events record whether their signature was verified.

### Signature settings

| Field | Values |
| - | - |
| `secret` | The sender's signing secret. Required. |
| `secret_encoding` | `text` (default) uses the secret as written. `base64` decodes it first, ignoring a leading `whsec_`. |
| `header` | Header that carries the signature, such as `X-Signature`. Required. Letters, digits, and hyphens only. |
| `format` | `whole` (default): the header value is the signature. `prefix`: the signature follows fixed text, such as `sha256=`. `list`: the header is a list, and the signature is the item under a key. |
| `format_value` | The prefix for `prefix`, or the key for `list`, such as `v1`. Required for both. |
| `algorithm` | HMAC with `sha256` (default), `sha1`, or `sha512`. |
| `encoding` | How the signature is written: `hex` (default) or `base64`. |
| `signed_content` | What the sender signed. Defaults to `{body}`. Must include `{body}` exactly once. |
| `timestamp_from` | `none` (default), `header`, or `list`: where to read the request's timestamp. |
| `timestamp_value` | The timestamp header name for `header`, or its key in the signature header for `list`, such as `t`. |
| `max_age_seconds` | Optional. Reject requests whose timestamp is more than this many seconds from now. Requires the timestamp to be signed: `{timestamp}` in `signed_content`, or `{header:<timestamp header>}` when `timestamp_from` is `header`. |

`signed_content` is a template. `{body}` is the raw request body, byte for byte. `{timestamp}` is the timestamp as sent, and needs `timestamp_from`. `{header:Name}` is the value of another request header. Anything else is literal text. For example, `v0:{timestamp}:{body}` signs `v0:`, the timestamp, `:`, and the body.

With `format: "list"`, the header holds `key=value` items separated by commas, such as `t=1700000000,v1=5257a8...`, or `key,value` pairs separated by spaces, such as `v1,K5oZ... v1,Ka8w...`. When the key appears more than once, a match with any of its first 10 values passes. `timestamp_from: "list"` reads the timestamp from the same header and needs `format: "list"`.

Timestamps are Unix time in seconds. Timestamps in milliseconds also work with `max_age_seconds`.

### Example settings

These settings match each service's documented signature. Check the sender's current documentation before you rely on them.

| Sender | `header` | `format` | `format_value` | `signed_content` | `timestamp_from` | `timestamp_value` | `encoding` | `secret_encoding` |
| - | - | - | - | - | - | - | - | - |
| Stripe | `Stripe-Signature` | `list` | `v1` | `{timestamp}.{body}` | `list` | `t` | `hex` | `text` |
| GitHub | `X-Hub-Signature-256` | `prefix` | `sha256=` | `{body}` | `none` | | `hex` | `text` |
| Slack | `X-Slack-Signature` | `prefix` | `v0=` | `v0:{timestamp}:{body}` | `header` | `X-Slack-Request-Timestamp` | `hex` | `text` |
| Shopify | `X-Shopify-Hmac-Sha256` | `whole` | | `{body}` | `none` | | `base64` | `text` |
| Standard Webhooks | `webhook-signature` | `list` | `v1` | `{header:webhook-id}.{timestamp}.{body}` | `header` | `webhook-timestamp` | `base64` | `base64` |

All five use `sha256`. For the senders with a timestamp, also set `max_age_seconds` to `300` to reject requests signed more than 5 minutes ago. A request repeated within that window is stored again. For Standard Webhooks, paste the secret as the sender shows it, with or without its `whsec_` prefix.

```json theme={null}
{
  "secret": "whsec_...",
  "secret_encoding": "base64",
  "header": "webhook-signature",
  "format": "list",
  "format_value": "v1",
  "encoding": "base64",
  "signed_content": "{header:webhook-id}.{timestamp}.{body}",
  "timestamp_from": "header",
  "timestamp_value": "webhook-timestamp",
  "max_age_seconds": 300
}
```

When a signed request's JSON body is `{"type": "url_verification", "challenge": "..."}`, Inkbox answers with `{"challenge": "..."}` and doesn't store an event. Slack sends this when you add the URL.

### Test with a sample request

Before you save settings, or after, [check a sample request](https://inkbox.ai/docs/api/identities/inbound.md#check-a-signature) against them. Paste the headers and the raw body from a request the sender delivered. Inkbox tells you whether the signature matched and, if not, why. It stores nothing. In the Console, use **Test with a sample request** in the source form.

## Handlers

### Agent

The default. The agent receives the event in a conversation for that source, along with the source's `instructions`. The agent sees the event as outside content from the named source, not as a message from you. There's no channel to reply on, so the agent acts with its tools: sending email, updating files, calling APIs.

Each delivery is saved on the agent's computer in `~/.inkbox/inbound/events/<delivery_id>/` as two files: `body`, the request body exactly as received, and `request.json`, with the method, query, headers, and event details. The agent gets the source name, whether the signature was verified, the content type and size, the folder's path, and your `instructions`. A text body of up to 4 KiB is also shown inline; for anything larger or binary, the agent reads `body` from the folder when it needs to. Event files are deleted after 7 days.

```json theme={null}
{"type": "agent", "instructions": "When a pull request is opened, review it and post a summary to the team by email."}
```

Instructions can be up to 4,000 characters.

### Script

Run a command on the agent's computer instead. Use a script to filter, transform, or handle events without an agent turn.

```json theme={null}
{"type": "script", "command": "python3 ~/hooks/stripe.py"}
```

The command runs in the agent's home directory with a 120-second timeout. It receives the whole event as JSON on stdin. Decode `body` according to `body_encoding`:

```json theme={null}
{
  "source": "stripe",
  "event_id": "inbev_8c1f2e47-9a3b-4d6e-b5c0-2f7a1d9e4b63",
  "headers": {"content-type": "application/json", "stripe-signature": "t=...,v1=..."},
  "body": "{\"id\":\"evt_...\",\"type\":\"invoice.payment_failed\"}",
  "body_encoding": "utf8"
}
```

What happens next depends on the result:

| Result | Outcome |
| - | - |
| Exit `0`, no output | Done. No agent turn. |
| Exit `0`, with output | The output goes to the agent in place of the request body, saved as `body` and shown inline when short. Up to 64 KiB of output is kept. |
| Non-zero exit or timeout | Runs up to 5 times in total, retrying after 10 seconds, 30 seconds, 2 minutes, and 10 minutes. If the last run fails, the event is marked `failed`. |

A script that prints nothing for routine events and a short note for important ones keeps the agent focused. For example, ignore successful payments and print a line for failed ones.

A script can run more than once for the same event: after a failure, after a replay, or if the computer restarts mid-run. Make it idempotent, for example by recording each `event_id` it has handled and skipping repeats.

## Responses to the sender

| Status | Meaning |
| - | - |
| `200` | Stored. The body is `{"received": true, "event_id": "inbev_..."}`. |
| `401` | Missing or invalid signature. |
| `404` | Unknown URL, or the agent is no longer hosted. |
| `405` | Method other than `POST`. The response includes `Allow: POST`. |
| `413` | Body larger than 1 MiB. |
| `429` | Too many requests. Limits are 30 stored events per minute for each source, about 20 requests per second for each URL, about 10 requests per second from one sending address, and 120 requests per minute from one address to one agent's URLs with an unknown URL or an invalid signature. Retry later, honoring `Retry-After` when present. |

Inbound responds before the agent sees the event, so senders that need the agent's answer in the HTTP response aren't supported.

## Not supported

Inbound accepts `POST` requests only and answers other methods with `405`. Apart from the signed URL verification challenge above, it answers every stored event with `200` and the JSON body above. These sender requirements aren't supported:

* Verification challenges sent as `GET`.
* Handshakes that expect a validation token echoed back, such as Microsoft Graph change notifications.
* Ed25519 signatures, such as Discord webhook events.
* Signatures computed over the URL and form parameters instead of the raw body, such as Twilio request validation.

A sender with an unsupported signature can still use a source without a signing secret, as long as it needs no handshake. The URL token is then the only check.

## Delivery and replay

Inkbox delivers each stored event to the agent and retries for up to 24 hours. Delivery wakes a sleeping computer and starts a stopped one, whether it stopped after being idle or you stopped it. Events that can't be delivered within 24 hours are marked `failed`. Each event's `status` is `pending`, `delivered`, or `failed`.

Inkbox keeps events until you delete the source or the agent, or remove hosting. [Replay](https://inkbox.ai/docs/api/identities/inbound.md#replay-an-event) any event to deliver it again, for example after fixing a script. You can also browse and replay events in the Console.

Deliveries can repeat. Use `delivery_id` to skip duplicates: it stays the same when Inkbox retries a delivery and changes when you replay the event.

## The `inbound.received` event

Your agent receives each event as an `inbound.received` payload, signed like other Inkbox events. This event goes only to the hosted agent; it isn't available as a [webhook subscription](https://inkbox.ai/docs/webhooks.md).

```json theme={null}
{
  "id": "evt_5b1e...",
  "event_type": "inbound.received",
  "timestamp": "2026-11-20T15:04:06Z",
  "data": {
    "event_id": "inbev_8c1f2e47-9a3b-4d6e-b5c0-2f7a1d9e4b63",
    "delivery_id": "6f0c2a8e-4d1b-4a7e-9c3f-0b2d5e8a1c47",
    "received_at": "2026-11-20T15:04:05Z",
    "source": {
      "id": "inbsrc_3d9a7c21-6e4f-4b8a-9d2c-1f5e8a7b0c34",
      "name": "stripe",
      "instructions": "Summarize failed payments and email the account owner."
    },
    "handler": {"type": "agent"},
    "signature_verified": true,
    "request": {
      "method": "POST",
      "query": {},
      "headers": {"content-type": "application/json", "stripe-signature": "t=...,v1=..."},
      "content_type": "application/json",
      "body": "{\"id\":\"evt_...\",\"type\":\"invoice.payment_failed\"}",
      "body_encoding": "utf8"
    }
  }
}
```

| Field | Meaning |
| - | - |
| `id` | Payload ID. The same for every retry of one delivery. |
| `event_id` | The stored event. The same across retries and replays; use it to [report a failure](https://inkbox.ai/docs/api/identities/inbound.md#report-a-failed-event) or look up the event. |
| `delivery_id` | One delivery of the event. The same across retries, new on each replay. Use it to skip duplicates and to report a failure. |
| `source` | The source's `id`, `name`, and `instructions` (or `null`). |
| `handler` | `{"type": "agent"}` or `{"type": "script", "command": "..."}`. |
| `signature_verified` | `true` when the source has a signing secret and the signature matched. |
| `request.headers` | The sender's headers, lowercased. Credentials and connection headers are removed. |
| `request.body` | The raw body, encoded as `request.body_encoding` says: `utf8` is the text as sent, and `base64` is the raw bytes in base64. Text bodies can also arrive as `base64`, for example when they are large, so always decode by `body_encoding`, not by content type. |

The Inkbox SDKs include a typed payload for this event.

## Connect Stripe

1. Create a source named `stripe` without a signing secret, and copy its `url`.

2. In the Stripe Dashboard, open **Developers** > **Webhooks** and add an endpoint with that URL. Choose the events your agent should handle.

3. Copy the endpoint's signing secret (`whsec_...`).

4. Set it on the source:

   ```bash theme={null}
   curl -X PATCH https://inkbox.ai/api/v1/identities/my-agent/inbound/inbsrc_... \
     -H "X-API-Key: $INKBOX_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"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}}'
   ```

5. Send a test event from Stripe and check it under the source's [events](https://inkbox.ai/docs/api/identities/inbound.md#list-events).

## Connect GitHub

1. Choose a secret, for example the output of `openssl rand -hex 32`.

2. Create a source with it:

   ```bash theme={null}
   curl -X POST https://inkbox.ai/api/v1/identities/my-agent/inbound \
     -H "X-API-Key: $INKBOX_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name": "github", "signature": {"secret": "YOUR_SECRET", "header": "X-Hub-Signature-256", "format": "prefix", "format_value": "sha256="}, "handler": {"type": "agent", "instructions": "Triage new issues and label them."}}'
   ```

3. In your repository or organization, open **Settings** > **Webhooks** > **Add webhook**.

4. Set **Payload URL** to the source's `url`, **Content type** to `application/json`, and **Secret** to the same secret.

5. Choose the events to send and save. GitHub sends a `ping` event that appears in the source's events.

## Connect other services

For services that sign with HMAC, find the signature header, what they sign, and how they encode it in their webhook documentation, then fill in the [signature settings](#signature-settings). The [example settings](#example-settings) cover common patterns. [Check a sample request](#test-with-a-sample-request) to confirm the settings before you rely on them. For services that don't sign, keep the URL private and rotate it if it leaks.


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