Skip to main content
Inbound lets other services send webhooks to your hosted agent. 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. 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:
The response includes the url to give the sender. With the Python SDK:
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:
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: --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. 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

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. 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.
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 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.
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.
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:
What happens next depends on the result: 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

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 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.
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:
  5. Send a test event from Stripe and check it under the source’s events.

Connect GitHub

  1. Choose a secret, for example the output of openssl rand -hex 32.
  2. Create a source with it:
  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. The example settings cover common patterns. Check 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.