Webhook
The webhook adapter is the one place a Blong process is reached rather than reaching: a platform posts to a path, the port verifies and maps what arrived, and a realm method decides what it means. The same port posts out, so a service that answers a platform can also speak to it, on one configuration.
Configuration
Everything is co-located in the layer that attaches the port, as an activation block. The keys are
the port's contract, and the receiving half is off until listen asks for it.
| Key | What it decides |
|---|---|
url | The base of the posting half; a descriptor's path resolves against it. |
listen | Starts the receiving half. Off by default: a notifier needs no socket. |
server | Where it listens. port: 0 is a real choice — the kernel picks and the port reports. |
path | The path a platform posts to, with {name} segments taken from the URL. |
hook | The prefix of the three receiving hooks; defaults to the namespace. |
mode | server acknowledges at once and runs on; reply waits and answers with the result. |
response | The acknowledgement body when mode is server or nothing else answers. |
destination | The realm method an inbound message is dispatched to. |
bodyLimit | Largest accepted body, in bytes. |
accounts | Whatever the port's own handlers need to find a secret per account. |
The three hooks
A receiving port provides up to three handlers, named <hook>.identity, <hook>.message and
<hook>.server. Each missing one degrades rather than fails, which is what lets a simulator be the
same port with fewer hooks.
identityverifies and names: a signature over the raw bytes, the account the path selects, the delivery id a retry repeats. A throw is answered with the error'sstatusCodeand nothing runs.messagemaps the payload into the realm's vocabulary. It answersfalsewhen the request is understood but there is nothing to process (a challenge, a delivery of a kind the port does not use), and theserverhook or the configuredresponseis the whole answer then.servershapes the answer once the chain has run. Inreplymode it also sees what the destination answered.
webhookBodyParser('json' | 'form') keeps request.rawBody beside the parsed body, because a
platform signature is computed over the bytes and not over their meaning, and maps a parse failure
to a 400.
Both directions on one port
The posting half turns a descriptor into one HTTP call and returns what the platform said:
export default handler(({lib: {error, slackTokenGet}}) => {
const errors = error({
'slack.accountMissing': {message: 'No Slack account {account}', statusCode: 404},
});
return function slackMessageSendRequestSend(this: {config?: IConfig}, params: ISendParams) {
const token = slackTokenGet(this.config?.accounts, params.account);
if (!token) throw errors['slack.accountMissing']({params: {account: params.account ?? ''}});
return {
path: 'chat.postMessage',
method: 'POST',
responseType: 'json',
headers: {authorization: `Bearer ${token}`},
json: {channel: params.conversationId, text: params.text},
};
};
});
A descriptor is deliberately boring — path, method, headers, body — so the protocol stays in the
handlers and the transport stays in the port. The port also answers <namespace>Webhook.address,
which is how a port configured with port: 0 is reached without agreeing on a number.
Receiving is a state machine, not a callback
Four things have to happen in order, and each one is a decision the port makes so the hooks do not have to:
- Acknowledge fast. Slack allows three seconds and Viber less; a realm that took longer would
be retried and would redo its work.
mode: 'server'answers fromresponsebefore the destination runs. - Deliver once. A retry is a platform's normal behaviour, not an error. The delivery id a
port's
identityhook returns is remembered for a bounded window — long enough to outlive one retry — and a repeat is acknowledged without running anything. - Disown on request. A
messagehook that answersfalsesays the request was for the port (a URL challenge), and theserverhook answers it. - Stop cleanly. The outbound stream ends with a
nullpush, anend(), and a deferreddestroy(), which is what keeps a hot reload from printingAbortErrorover the work it just interrupted.
Example: chat as a platform surface
realm/blong-chat is the worked example. adapter/server/slack.ts and adapter/server/viber.ts
extend adapter.webhook with listen, a path built from {appId}/{clientId}, mode: 'server',
a destination of chat.in.receive, and a hook prefix (slackIn, viberIn) whose three
handlers do the protocol work:
| Slack handler | What it does |
|---|---|
slackIn.identity | HMAC of v0:{timestamp}:{body}, 300 s skew, timing-safe, one account. |
slackIn.message | event_callback → a message; block_actions → an answer or a form request; view_submission → an answer. |
slackIn.server | Answers url_verification with the challenge. |
The realm then sees one vocabulary — IChatInbound — whatever arrived, and the platform never
reaches the business logic. Adding a third platform is a port and its hooks, not a change to the
realm.
Deploying the receiving half
A webhook port is reachable only if a deployment publishes it, so the layer declares the port and
the ingress in its own activation.default:
k8sPorts: {chatSlack: {port: 8095}},
k8sIngresses: {chatSlack: {path: '/chat/slack', servicePort: 8095}},
@feasibleone/blong-kustomize turns that into an Ingress and appends the port to the owning
deployment's Service beside rpc and http, so an Ingress has endpoints without a second
declaration.
A webhook wants a host of its own
Ingress annotations belong to the host, not to a path: the controller has no per-path
annotations. So a webhook path on a portal's host inherits the portal's authentication — an oauth2
portal would ask a machine for a browser login, a basic one for a password that exists so a human
can read a page. The tree refuses that combination rather than writing a webhook nobody can call, and
names both sides when it does.
A webhook therefore lands on its own host, and one host carries every path the deployment serves there:
k8sIngresses: {
chatSlack: {
path: '/chat/slack',
host: 'chat-hook.example',
servicePort: 8095,
tls: {secretName: 'chat-hook-tls'},
// The host's annotations, which is why a second path on it needs none.
annotations: {'cert-manager.io/cluster-issuer': 'letsencrypt-prod'},
},
},
Two fields are load-bearing and are easy to leave out:
host— a contributed path with no host lands on the host of whatever else is published, which is the portal and its authentication.annotations— an Ingress naming a TLS secret is not an Ingress with a certificate. Nothing asks cert-manager for it, no handshake completes, and the platform's own request URL answers nothing. The annotations are the host's, so one entry beside the certificate is enough for every path there.
A portal's host and annotations come from the deployment rather than the source tree — the k8s
intent's rc file and the CR name them. A contributed webhook host is the same: the realm contributes
the path, the port and what the host's annotations must say, and the deployment names the address in
kustomize.deploy.ingresses (a local run) or spec.ingresses (a CR), keyed by the contribution's
alias.
Testing it
A platform is a simulator port: the same adapter.webhook, mode: 'reply', no identity hook, and
a server hook that records what arrived and answers the smallest body its caller accepts. The
client side is a signed HTTP request the test builds with the platform's own algorithm, which is
what makes the signature, the parser and the mapping one assertion rather than a stub's opinion. See
test for the tap layer and realm/blong-chat/sim/ for the pair in use.