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
stripeorgithub. 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.
url to give the sender.
With the Python SDK:
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:
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 with401. 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.
{"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’sinstructions. 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.
Script
Run a command on the agent’s computer instead. Use a script to filter, transform, or handle events without an agent turn.body according to body_encoding:
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 acceptsPOST 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.
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 markedfailed. 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
-
Create a source named
stripewithout a signing secret, and copy itsurl. - In the Stripe Dashboard, open Developers > Webhooks and add an endpoint with that URL. Choose the events your agent should handle.
-
Copy the endpoint’s signing secret (
whsec_...). -
Set it on the source:
- Send a test event from Stripe and check it under the source’s events.
Connect GitHub
-
Choose a secret, for example the output of
openssl rand -hex 32. -
Create a source with it:
- In your repository or organization, open Settings > Webhooks > Add webhook.
-
Set Payload URL to the source’s
url, Content type toapplication/json, and Secret to the same secret. -
Choose the events to send and save. GitHub sends a
pingevent that appears in the source’s events.

