Webhooks and OAuth in the emulator
Providers send webhooks to public HTTPS addresses, but the emulator is only reachable from your machine. A tunnel and a small relay connect the two.
Receive webhooks
Section titled “Receive webhooks”A tunnel service, such as ngrok or Cloudflare Quick Tunnels, gives you a temporary public address. It cannot forward straight to the emulator, because:
- the emulator finds the vertex by its hostname, both in TLS and in the
Hostheader, - the connection must trust the emulator’s certificates,
- tunnels add
X-Forwarded-*headers, and the emulator rejects requests that have them.
This relay handles all three. Save it outside your application:
// Forwards a public tunnel to one emulator runtime origin.// Usage: node relay.mjs https://exec-<id>.emulator.localhost:51003import http from "node:http";import https from "node:https";import { readFileSync } from "node:fs";import { homedir } from "node:os";import { join } from "node:path";
const target = new URL(process.argv[2]);const ca = readFileSync(join(homedir(), ".config/adaptkit/emulator/certs/rootCA.pem"));const port = Number(process.env.PORT ?? 51080);
http .createServer((request, response) => { const headers = { ...request.headers, host: target.host }; // The emulator rejects requests with these headers, which tunnels add. delete headers["x-forwarded-for"]; delete headers["x-forwarded-host"]; delete headers["x-forwarded-proto"]; const upstream = https.request( { host: "127.0.0.1", port: target.port, servername: target.hostname, // TLS SNI ca, // Trust the emulator's local certificate authority. method: request.method, path: request.url, headers, }, (answer) => { response.writeHead(answer.statusCode ?? 502, answer.headers); answer.pipe(response); }, ); upstream.on("error", (error) => response.writeHead(502).end(String(error))); request.pipe(upstream); }) .listen(port, "127.0.0.1", () => { console.log(`Relaying http://127.0.0.1:${port} to ${target.origin}`); });-
Upload your application, and start a run of the vertex that receives the webhooks.
-
Find the vertex’s address in
executorUrl:Terminal window curl -s http://localhost:51001/v1/emulator/vertices/payment_request -
Start the relay with that address, and a tunnel to the relay:
Terminal window node relay.mjs https://exec-….emulator.localhost:51003ngrok http 51080 # or: cloudflared tunnel --url http://localhost:51080 -
Give the tunnel’s address to your application with a development callback URL, and trigger the provider’s test events.
The vertex’s address can change with each upload and run. Then restart the relay with the new one. Keep your signature checks on: the tunnel makes your application reachable from the internet.
Add a development callback URL
Section titled “Add a development callback URL”In Adapt, your application gives the provider its own public address. In the emulator, that address only works on your machine. Add an optional system service for a tunnel address:
{ "serviceDefinitions": [ { "name": "dev_callback_base_url", "label": "Development callback URL", "description": "Only for local development: a public HTTPS tunnel URL that forwards to the emulator. Leave it empty in production.", "optional": true, "variable": { "schema": { "type": "string" }, "plaintext": true } } ], "systemServices": ["dev_callback_base_url"]}Use it only when it is set:
import type { SessionExecutorApi } from "@mochabug/adapt-sdk/api";
// The development tunnel, if the author set one. Otherwise the vertex's own public host.async function callbackOrigin(api: SessionExecutorApi, publicHost: string | undefined) { const configured = await api.getSystemServices(); if (configured["dev_callback_base_url"]) { return await api.getSystemVariable<string>("dev_callback_base_url"); } return `https://${publicHost}`;}Call it from onStart with request.host?.publicHost, which Adapt sets for Browser and External vertices. Validate the value, and set the service only in the emulator.
Connect OAuth2 accounts
Section titled “Connect OAuth2 accounts”-
In your OAuth client’s settings at the provider, add this redirect URI:
http://localhost:51001/v1/emulator/oauth2/authorization-code/callbackBefore you publish, also add the callback URL that Adapt shows in your application’s system service settings.
-
On the emulator’s Services page, add your client secret to the OAuth2 system service.
-
Add a resource for the vertex’s OAuth2 service, and start the consent. Sign in at the provider and approve. The emulator stores the tokens.
A consent expires after 10 minutes if you do not finish it. If you change the system service, connect the accounts again. Some providers allow only one redirect URI per client, so check their rules first.