Validate your validation URL

Before submitting your application to homologation or triggering the first real installation, make sure your validation URL is answering Appmax's health check correctly. This tool fires a synthetic POST — with the exact payload Appmax uses on POST /app/client/generate — and runs every assertion of the contract.

What is the health check?

During the last step of app installation, Appmax fires a server-to-server POST against the validation URL configured on the panel. Your URL must answer HTTP 200 + JSON with an external_id UUID for the installation to be completed. Full contract at App installation and external-id.

URL de validação do seu aplicativo

Será enviado um POST com o mesmo payload que a Appmax usa durante POST /app/client/generate.

What is validated

The tool fires two requests in sequence with distinct external_key values. That allows comparing the external_id returned in each one and catching handlers that respond with a hardcoded UUID — a common bug that silently breaks new installations.

Assertion	Criterion
URL reachable	The URL responds within 8 seconds without DNS, connection-refused or TLS errors.
HTTP 200	Status code is exactly `200`. When another code appears, the detail tries to classify the cause (anti-bot WAF, auth, 5xx).
Returns `external_id` as valid UUID	Body parses as JSON and the `external_id` field is present as a string in the `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` (8-4-4-4-12 hex) format.
`external_id` changes per request (not hardcoded)	The second call (with a different `external_key`) returns a distinct UUID. If they match, your handler is hardcoded — each installation needs a unique `external_id`.

Why these assertions?

The real contract is simple: Appmax needs a 200 with a UUID external_id that is unique per installation. The tool runs the scenario twice and shows both UUIDs side by side so you can compare.

The payload sent

The tool fires the same shape Appmax uses for the real health check:

json

{
  "app_id": "DEMO_APP_ID",
  "client_id": "DEMO_CLIENT_ID",
  "client_secret": "DEMO_CLIENT_SECRET",
  "client_key": "DEMO_EXTERNAL_KEY",
  "external_key": "DEMO_EXTERNAL_KEY"
}

The values are obvious placeholders so they show up in your server log as a test call. In production, Appmax sends the real merchant client_id/client_secret — your handler needs to accept any payload in this shape.

Expected response from your handler

json

{
  "external_id": "37bb0791-ee0b-457d-860c-186e32978bcd",
  "alias": "My Store"
}

Persist the external_id

The UUID you return here isn't disposable — it becomes the current identifier of the installation and is required on every CDN call from the front-end. Every new installation requires a new value from Appmax, and the previous one stops being valid. See external-id for the full life cycle.

Limitations of this tool

No calls to private IPs: the tool refuses URLs that resolve to localhost, 10.x, 192.168.x, 172.16-31.x or link-local — use ngrok / beeceptor to expose a local endpoint.
No following redirects: a 302 is treated as failure — Appmax's real health check also doesn't follow redirects.
8s timeout: if your URL doesn't respond within that window, you get Timeout (Appmax's production timeout is larger, but delays > 5s are considered an operational issue).
HTTPS or HTTP: both accepted here, but in production Appmax only calls HTTPS URLs — refuse HTTP on your final domain.

When to use

Before submitting the app for homologation.
After updating the health-check handler.
When an installation fails with a 500 on POST /app/client/generate — most likely the validation URL didn't answer as expected. See Troubleshooting.

Validate your validation URL ​

What is validated ​

The payload sent ​

Expected response from your handler ​