# Call other systems from an app

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"
     }
   ]
   ```

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

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:

| 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, 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

| 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 |

## Next steps

- [App files](/docs/app-files)
- [Build an app](/docs/build-an-app)
- [Integrations](/docs/integrations)
- [Receive webhooks from Volobox](/docs/receive-webhooks)
