Automation and apps

Guide

Call 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

  1. 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".

  2. 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"
      }
    ]
KeyMeaning
nameHow rules read it, as env.BILLING_TOKEN: capital letters, digits and underscores
requiredtrue when the app cannot work without it: a publish stops until it is bound
hostsThe hosts the rules send it to, proposed to whoever binds it. A proposal grants nothing
formaturl for a secret that is a whole address, such as a chat webhook URL
descriptionWhat 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.

  1. Have the endpoint that marks a deal won announce it:

    JavaScript
    await events.publish("deal.won", { id: deal.id });
  2. 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_TOKEN is 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.ok or answer.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 shorthands http.get, http.post, http.put, http.patch and http.delete answer { status, ok, headers, text, json, skipped }. auth is { bearer } or { basic: { user, password } }.
  • Requests go over https to public internet addresses only, within per-run and per-app limits. A redirect is not followed; it comes back with its location header.

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

  1. In the Builder, open Settings > Secrets. Each declared secret has a row showing what the Published app and the Draft send, or Not bound.
  2. Choose Bind under the environment you want.
  3. 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, no https://, path or port).
  4. Choose Bind.
  5. 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.

  1. 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();
    }
  2. Bind the secret under Settings > Secrets, leaving Hosts it may be sent to empty. It is never sent anywhere; it only checks signatures.

  3. Publish the app. Another system reaches only the published app's endpoints.

  4. 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:

    Text
    https://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-serialized body. crypto.verifyHmac({ key, data, signature, algorithm, encoding, prefix }) answers true or false; algorithm is sha256 (default), sha1 or sha512.
  • A sender that sends its secret as a token instead of signing (GitLab's X-Gitlab-Token) is checked with await crypto.verifySecret({ key: env.GITLAB_WEBHOOK_TOKEN, value: headers["x-gitlab-token"] }). Never compare headers[...] === 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:

HelperStatusUse it when
badRequest(message)400What was sent cannot be used
forbidden(message)403The caller is not who they claim, such as a bad signature
notFound(message)404The record does not exist, or is not the caller's
conflict(message)409The work is already done, or the record moved on
ok(body), created(body), noContent()2xxIt 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, as SecretHostNotAllowed. A caller of the endpoint sees only AppNotSetUp (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

SymptomFix
The secret "may not be sent to" a hostAdd 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 boundBind the secret for that environment; the draft and the published app are bound separately
An endpoint answers 503, the app is not fully set upA secret it needs is not set up for that version. Its run under Structure > Runs names which one
A webhook is refused as forbiddenThe 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 429Calls without signing in are limited per address; ask the deployment's administrator to raise the limit
The scope is not offered when you bindYou 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 refusedRules reach only public internet addresses

Next steps