Webhooks and callbacks

Twins deliver vendor callbacks into your app.

--expose <port> publishes a port on your machine at a public HTTPS URL, so a sandbox can deliver callbacks to an app running locally.

Vendors that originate outbound calls have twins that do the same. The Webhooks column in All twins says which vendors those are, and the --expose flags are listed in veris.

To take callbacks on a receiver listening on port 3000:


veris run --expose 3000 -- pytest -q

Your app receives that URL in VERIS_PUBLIC_URL. The run reports what arrived:


veris: callbacks arrive at https://odd-forest-1a2b.trycloudflare.com
veris: your app received 2 callback(s):
  POST   /hooks/stripe                2 -> 200

--require-callback /hooks/stripe fails the run if nothing arrived.

The callback URL is a capability. Anyone holding it can POST to your app.

Registration

Your code registers VERIS_PUBLIC_URL through the vendor’s own webhook registration endpoint. Veris does not register it for you.

One sandbox per run

The callback destination is a single setting per sandbox, so two runs sharing one sandbox overwrite each other’s URL. --fresh gives each run its own sandbox. A run that attaches to a sandbox instead warns when it replaces an existing URL.

Ports

8081 and 8443 are reserved. Your receiver must listen on another port.
Your container cannot publish its own ports. Use --expose.

Delivery failures

Delivery failures are armed like any other fault, and every attempt is recorded. See Failures and faults.

A frozen clock stops delivery: a callback is delivered when its due time arrives, and with the clock stopped nothing is ever due.

Without the proxy

Expose your own receiver, register its URL with veris up --callback-url <url>, then verify the sandbox can reach it. veris doctor prints the registered URL and whether the sandbox’s probe of it answered; the POST re-runs that probe.


veris doctor

$CONTROL_URL is one twin’s control URL, printed by veris sandbox services get — see the control plane.


curl -X POST "$CONTROL_URL/veris/client/probe" -d '{}' \
  -H 'Content-Type: application/json'

Private and loopback addresses are refused.