App identifiers and URLs

After creating the application, the panel exposes a set of identifiers and URLs under View Application → Develop. This page is the per-field reference, and the point in the flow where each one is consumed.

Identifiers

Your application has two different identifiers in the panel. Mixing them up is the most common cause of 422 Unprocessable Entity in the installation flow.

Identifier	Format	Where to use
App UUID	f9e8d7c6-b5a4-3210-fedc-ba0987654321	In every API endpoint (including POST /app/authorize), except where a field is explicitly marked as "Numerical ID".
App Numerical ID	699 (integer)	Only in fields explicitly marked as "Numerical ID" (rare).

Use the UUID, not the Numerical ID

In POST /app/authorize, always send the App UUID in the app_id field. If you send the Numerical ID, you receive 422 Unprocessable Entity.

POST /app/client/generate takes no application identifier at all — its body is just { "token": "<hash>" }, and the app is identified by the Bearer of the application credentials.

The Numerical ID shows up in exactly one place in the flow: as the app_id of the payload Appmax sends to your validation URL during the health check. You receive it, you never send it.

If you're getting 422 on authorize, first check which of the two IDs you're sending. Full diagnostics at Installation troubleshooting.

Configured URLs

The panel shows four URLs tied to the application. Each is used at a different point of the lifecycle.

Host

Base URL of your system. Used by Appmax as the destination of merchant event webhooks.

• Caller: Appmax
• Receiver: your system
• When: throughout merchant operation, whenever a configured event occurs

Envelope details and the 29 available events in Webhooks.

System URL

Public URL of your system, made available to the merchant for access after installation. It is not used by Appmax in server-to-server calls — it's just the link displayed on the merchant panel.

• Caller: merchant (manual click in the panel)
• Receiver: your system
• When: when the merchant wants to access your app's panel/settings

Validation URL

Endpoint on your system that Appmax calls during POST /app/client/generate to register the installation — this is the health check.

• Caller: Appmax (server-to-server)
• Receiver: your system
• When: once per installation, during the last step of the flow

Contract:

Direction	Payload
Appmax → your system (POST)	{ app_id, client_id?, client_secret?, client_key?, external_key? } — only app_id (Numerical ID, numeric) is guaranteed; all other fields are optional
Your system → Appmax (200 OK)	{ "external_id": "<UUID v1-v5>", "alias"?: "<store name>" }

The external_id you return is generated by your system and becomes the current identifier of that installation — it's the same value later consumed by Appmax JS at checkout as the external-id header. Every new installation requires a new value from Appmax, and the previous one stops being valid.

The installation fails if the validation URL doesn't answer correctly

If your validation URL isn't public, responds with a status other than 200, or doesn't return a valid external_id UUID, POST /app/client/generate aborts with 500 and no merchant credentials are issued. Test it first at Validate installation URL.

Full contract details, payload examples, and error handling in Installation flow — health check. external_id lifecycle (generation in the health check, usage in the front via CDN) in external-id.

Webhook URL

Where Appmax sends notifications for events selected at step 3 of app creation (order created, paid, refunded, etc.).

• Caller: Appmax
• Receiver: your system
• When: whenever a subscribed event occurs on the merchant's platform

Envelope, event list, and per-type examples in Webhooks.

Summary — which URL is called for what

URL	Direction	Triggered by
Host	Appmax → you	Webhook event
System URL	Merchant → you	Manual access via panel
Validation URL	Appmax → you	Health check on POST /app/client/generate
Webhook URL	Appmax → you	Event subscribed at app creation

Next steps

• Validate installation URL — interactive tool to check the validation URL contract.
• Installation flow — use the App UUID and validation URL in production.
• Webhooks — payloads and per-event examples delivered to Host / Webhook URL.
• external-id — lifecycle of the identifier returned by the validation URL.