Automation and apps
GuideCall other systems from an app
Have an app rule call a REST API with a secret an Admin binds, receive a signed webhook on an endpoint, and handle refusals on both sides.
At the end of this guide your app does two things with another system: a rule creates an invoice in a billing system's REST API when a deal is won, sending an API token the app never holds, and an endpoint receives GitHub webhooks and checks their signature before it keeps anything. You will also know how each side refuses. A Builder or Admin of the app does the work; binding a secret takes one who was given the workspace secret's scope.
Before you begin
- Builder or Admin on the app.
- A workspace secret scope you were given (someone who manages secrets adds you under Who may use this scope in Organization Settings > Secrets), holding the other system's token. You can also add the value while you bind, if you may manage workspace secrets.
- The other system's API host name, such as
api.billing.example, and, for webhooks, a sender that signs its requests.
Declare the secret
-
Ask the agent in the Build tab, for example: "when a deal is won, create an invoice at api.billing.example with the token in the BILLING_TOKEN secret".
-
Check
app.json. The agent declares the secret there, never its value:JSON"secrets": [ { "name": "BILLING_TOKEN", "required": true, "hosts": [{ "host": "api.billing.example", "required": true }], "description": "Billing API token" } ]
| Key | Meaning |
|---|---|
name | How rules read it, as env.BILLING_TOKEN: capital letters, digits and underscores |
required | true when the app cannot work without it: a publish stops until it is bound |
hosts | The hosts the rules send it to, proposed to whoever binds it. A proposal grants nothing |
format | url for a secret that is a whole address, such as a chat webhook URL |
description | What it is for, for the person who binds it |
Write the rule that calls the API
Write to another system from an event rule (or a schedule), which runs after the app's change is saved and is tried again when it fails. An operation rule only reads (GET), because a change elsewhere would stay even if the save were undone.
-
Have the endpoint that marks a deal won announce it:
JavaScriptawait events.publish("deal.won", { id: deal.id }); -
Have an event rule make the request:
JSON{ "id": "invoice-won-deal", "kind": "event", "event": "deal.won", "file": "rules/invoice-won-deal.js", "description": "Creates an invoice in the billing system for a won deal." }JavaScript// rules/invoice-won-deal.js export default async function ({ payload, db, env, http }) { const deal = await db.Deal.get(payload.id); const answer = await http.post( "https://api.billing.example/v1/invoices", { customer: deal.customerEmail, amount: deal.amount }, { auth: { bearer: env.BILLING_TOKEN }, headers: { "Idempotency-Key": `deal-${deal.id}` } }, ); if (!answer.ok) throw new Error(`Billing refused the invoice: ${answer.status}`); await db.Deal.update(deal.id, { invoiceId: answer.json.id }); }
env.BILLING_TOKENis a placeholder. Volobox puts the value in only when the request goes to a host the secret is bound to; the rule never sees or logs it, and a value the answer echoes back comes back as***.- A 4xx or 5xx answer does not throw. Check
answer.okoranswer.status; throwing makes the event rule try again. - Send an idempotency key when the other system takes one, because a retried event rule sends the request again.
http.request({ method, url, headers, auth, body, form, binary, multipart, responseEncoding, timeoutMs })and the shorthandshttp.get,http.post,http.put,http.patchandhttp.deleteanswer{ status, ok, headers, text, json, skipped }.authis{ bearer }or{ basic: { user, password } }.- Requests go over
httpsto public internet addresses only, within per-run and per-app limits. A redirect is not followed; it comes back with itslocationheader.
Warning: Never write a token into the files
Anyone who can read the app's files would see it. Declare a secret and send env.NAME.
Bind the secret
- In the Builder, open Settings > Secrets. Each declared secret has a row showing what the Published app and the Draft send, or Not bound.
- Choose Bind under the environment you want.
- Choose the Secret scope and its Secret key. The hosts the app's files name are listed under The app's rules send it to, already ticked except for a wildcard; add any others under Other hosts, one host name per line (
api.billing.example, nohttps://, path or port). - Choose Bind.
- Bind the draft separately, ideally to a test system and a test key: a Builder's tries run the draft's rules.
Note
In a Builder's test run, reads go out for real, but a change (POST, PUT, PATCH, DELETE) goes out only to a host of one of the draft's bindings. Anything else is listed as not sent.
Receive a webhook
Another system calls the app through an endpoint open to anyone, marked as called by other systems (a sender cannot solve the proof of work Volobox asks of visitors' browsers). The rule checks the sender itself.
-
Ask the agent, for example: "log the GitHub webhooks of our repository; check the signature with the GITHUB_WEBHOOK_SECRET secret". It writes:
JSON"rules": [ { "id": "github-webhook", "kind": "endpoint", "method": "post", "route": "/github", "calledByOtherSystems": true, "file": "rules/github-webhook.js", "description": "Logs GitHub webhook deliveries after checking their signature." } ], "secrets": [{ "name": "GITHUB_WEBHOOK_SECRET", "description": "GitHub webhook signing secret" }], "access": { "endpoints": { "github-webhook": ["anyone"] }, "openToAnyone": [{ "target": "endpoint:github-webhook", "quote": "log the GitHub webhooks of our repository" }] }JavaScript// rules/github-webhook.js export default async function ({ headers, rawBody, body, env, crypto, db, ok, forbidden }) { const signed = await crypto.verifyHmac({ key: env.GITHUB_WEBHOOK_SECRET, data: rawBody, signature: headers["x-hub-signature-256"], prefix: "sha256=", }); if (!signed) return forbidden("The signature does not match."); await db.Delivery.create({ deliveryId: headers["x-github-delivery"], event: headers["x-github-event"], repository: body.repository ? body.repository.full_name : null, }); return ok(); } -
Bind the secret under Settings > Secrets, leaving Hosts it may be sent to empty. It is never sent anywhere; it only checks signatures.
-
Publish the app. Another system reaches only the published app's endpoints.
-
Give the sender the endpoint's address and the same secret. In GitHub, add the webhook in the repository's Settings > Webhooks with content type
application/json:Texthttps://volobox.example.com/api/app/app-platform/apps/{address}/published/endpoints/github
- Check the signature over
rawBody, the text that arrived, never over a re-serializedbody.crypto.verifyHmac({ key, data, signature, algorithm, encoding, prefix })answerstrueorfalse;algorithmissha256(default),sha1orsha512. - A sender that sends its secret as a token instead of signing (GitLab's
X-Gitlab-Token) is checked withawait crypto.verifySecret({ key: env.GITLAB_WEBHOOK_TOKEN, value: headers["x-gitlab-token"] }). Never compareheaders[...] === env.NAME: that compares the placeholder and is always false. - Make the delivery's id unique, so a sender's retry writes nothing twice, and answer quickly: do slow work, and any request to another system, in an event rule.
- A rule can hand out its own address with
app.endpointUrl(route, query).
Handle refusals
On the endpoint side, answer with a response helper; the caller sees its status and message, and nothing the rule wrote is kept for an answer of 400 or more:
| Helper | Status | Use it when |
|---|---|---|
badRequest(message) | 400 | What was sent cannot be used |
forbidden(message) | 403 | The caller is not who they claim, such as a bad signature |
notFound(message) | 404 | The record does not exist, or is not the caller's |
conflict(message) | 409 | The work is already done, or the record moved on |
ok(body), created(body), noContent() | 2xx | It worked |
throw userError("...") refuses with a message the person sees from any rule, and undoes everything the run wrote. An endpoint that declares its body with export const input is checked before it runs: a call that breaks it answers 400 with { error, errors: [{ field, code, message }] }.
On the request side:
- A request sending a secret that is not bound is refused as
SecretNotBound; one to a host the binding does not allow, asSecretHostNotAllowed. A caller of the endpoint sees onlyAppNotSetUp(503), so a webhook's sender retries rather than failing for good. - A change sent from an operation rule is refused as
HttpWriteInOperation. - A failed request in an event rule that throws is tried again later.
Check that it works
- Settings > Secrets shows the secret bound for the Published app (and the Draft), and What the published app needs on Review shows it as set up.
- Structure > Runs lists each rule run, with each request's method, host, path, status and duration and the names of the secrets it sent, never a header, body or value.
- GitHub's webhook page shows the deliveries answered with 200, and the app holds one record per delivery.
Troubleshooting
| Symptom | Fix |
|---|---|
| The secret "may not be sent to" a host | Add the host to that environment's binding with Change the published binding or Change the draft binding in the row's ⋯ menu |
| Refused as not bound | Bind the secret for that environment; the draft and the published app are bound separately |
| An endpoint answers 503, the app is not fully set up | A secret it needs is not set up for that version. Its run under Structure > Runs names which one |
| A webhook is refused as forbidden | The signature or token did not match: check that the sender and the binding use the same secret, and the algorithm the rule checks (GitHub: sha256) |
| A busy sender gets 429 | Calls without signing in are limited per address; ask the deployment's administrator to raise the limit |
| The scope is not offered when you bind | You were not given it. Ask whoever manages secrets to add you under Who may use this scope |
| A request to an address in your own network is refused | Rules reach only public internet addresses |