Callbacks
A callback is a request Zyvra sends after a mock has answered, right away or later: a webhook to your app, an asynchronous result, a call to another mock service. Open an endpoint and choose the Callbacks tab. All of an endpoint’s callbacks are defined there, in one place, each with its own trigger.
When a callback is sent
Every callback has a Send when:
- Every time this endpoint answers.
- Only when…, where every part you set has to hold (within a part, any one choice will do):
- Response status: a code (
404) or a class (2xx,4xx,5xx), as many as you like. - Scenario that answered.
- Rule that answered: it matched, or it did not and its “otherwise” response answered.
- Request has: the same conditions as a rule (a header, a query value, a field in the body, and so on).
- Response status: a code (
“Send it if the response is a success” is status 2xx. “Send it if the request has this value” is a request condition. A summary line under the trigger reads what you set back in plain words.
A callback with no trigger chosen, or one that points at a scenario or rule that no longer exists, is never sent. The editor warns about it, and the tab shows a mark, so it cannot be forgotten.
What it sends
| Part | Notes |
|---|---|
| Target | Another mock service of the project (a path such as /hooks/paid), or a URL. Addresses outside this machine and private networks are refused unless the project allows them (callbackPolicy.allowExternal in zyvra.yaml). Redirects are not followed. |
| Method and delay | POST, PUT, PATCH, DELETE or GET, right away or up to 24 hours later. |
| Params | Query parameters, encoded for you. |
| Headers | X-Zyvra-Request-Id is added so the receiver can tell which request caused the call. |
| Body | JSON, form fields, text, or none. |
| Auth | Bearer token, basic, an API key in a header or the query, or an HMAC signature of the body (you choose the header, the algorithm and a prefix such as sha256=). |
| Settings | Retries on a network error or a 5xx (up to 5, with a delay between), a timeout of 1 to 60 seconds, and a switch to skip checking the target’s certificate (for a local server with a self-signed one). |
Values can use {{ }} expressions:
| Expression | What it is |
|---|---|
{{request.…}} | What was asked: {{request.path.id}}, {{request.body.user.name}}, {{request.headers.x-trace}} |
{{response.status}}, {{response.body.…}}, {{response.headers.…}} | What the mock answered |
{{scenario}} | The name of the scenario that answered |
{{env.name}} | A variable of the local environment. Secret values kept in the Vault are not available here. |
Credentials in a callback are saved in the project file, so use {{env.name}} to read a variable instead of writing a secret into it. A callback’s detail masks credential headers (Authorization, API keys, signatures) instead of showing them back.
Client certificates
An https callback presents the client certificate declared for its host (API Client → Certificates, the same ones the API Client uses) and trusts that certificate’s CA file. If a declared certificate cannot be loaded, the callback fails with the reason, without retries, rather than going out without it. The callback list shows which certificate was presented.
Saving the answer into state
In a callback’s Settings, Save its answer into state keeps something from the answer when it comes: add or replace a record, always add one, or change fields of one, in any state collection. The record’s id and fields can use:
{{callback.status}},{{callback.ok}}(a 2xx),{{callback.body.…}}(JSON, else text),{{callback.headers.…}}- everything above (
{{request.…}},{{response.…}},{{scenario}}) as it was when the request came in.
It is saved once the callback has finished, and only if an answer came back: a network error saves nothing. A string that is exactly one expression keeps its type, so {{callback.status}} is saved as the number 200. The callback’s detail says what was saved, with a link to the collection, or why it could not be.
Seeing and controlling them
- Traffic → Callbacks sent lists them: waiting, delivered, failed or not scheduled, with the answer and the reason. With callbacks from several services they are grouped by service, folded when there are many, and searchable.
- A request’s own detail in Traffic lists the callbacks it triggered, right under its heading.
- A waiting callback can be sent now or cancelled. Waiting callbacks are kept across a restart; one that was due more than 15 minutes before Zyvra started again is marked missed instead of firing late.
- A callback that triggers another is limited to a chain of 5, so a loop stops.
Older projects
Callbacks used to be set on a scenario or a rule. They keep working, and when you open such an endpoint they are listed on the Callbacks tab with the scenario or rule as the trigger, so they are sent in the same cases. Saving writes them in their new place.