Webhook Registration

Requirements

You need to register and verify the endpoint you'd like to receive webhooks. The Order Submit API will POST to this endpoint as events occur, retrying if your endpoint does not return a valid response in time.

Before you register

Registration is not a reservation. The moment you call /api/callback/create, we POST to your endpoint and expect it to answer. Deploy the endpoint first, then register it.

Your endpoint must already:

• be deployed and serving traffic on a public HTTPS URL,
• answer POST with a 2xx status, and
• accept the verification POST, which arrives as application/x-www-form-urlencoded with a single verifier field.

POST /api/callback/create

Content-type: application/json

Example Request

1
2
3
4
curl https://apps.whcc.com/api/callback/create  \
	-H "Authorization: Bearer 726670514499" \
	-F callbackUri=https://path.to.your/webhook/endpoint \
	-X POST

We will immediately POST to callbackUri with a parameter verifier with a unique verification code. Use the endpoint below to submit this verification code to prove you control the endpoint and enable webhooks to be sent to that address.

POST /api/callback/verify

Content-type: application/json

Example Request

1
2
3
4
curl https://apps.whcc.com/api/callback/verify  \
	-H "Authorization: Bearer 726670514499" \
	-F verifier=a53ae191-00f3-44f4-810c-19d88a5b4c16 \
	-X POST

Your webhook endpoint is now setup and ready to go.

Troubleshooting 400.05

400.05 — Unable to post a unique verification code to provided URI — means our verification POST did not get a successful response from your endpoint. It is a single error covering several unrelated causes.

Start by checking your own access log for our POST. That one observation splits the causes in half.

If your log shows the POST arriving

1. Your endpoint returned a 4xx or 5xx status. Only a 2xx completes the registration. A 3xx is a separate case — see the redirect warning below.
2. Your endpoint rejected the request body. The verification POST is application/x-www-form-urlencoded with a single verifier field. It is not JSON. An endpoint written to parse only JSON may answer 400 or 415 here and then handle every real webhook correctly.
3. Your endpoint answered, but took too long. We give up after 100 seconds. Answer the verification POST straight away and do any real work afterwards — the same rule that applies to webhook deliveries.

If your log shows nothing

1. Your server must accept TLS 1.2. We negotiate TLS 1.2 specifically. An endpoint configured to require TLS 1.3 and refuse 1.2 fails the handshake, and nothing reaches your application.
2. Your certificate must be valid and trusted. We validate it. An expired, self-signed or hostname-mismatched certificate fails the handshake — including the case where you clicked through the warning in a browser and assumed it was fine.
3. The endpoint must be reachable from the public internet. Check it from a network that is not your own — not from the machine running it, and not from your office. A firewall rule, an IP allowlist or geo-blocking produces this symptom.
4. The endpoint must already be deployed. We POST during the create call itself, not later.

Retrying is safe. Because each create mints a fresh verifier and leaves your callback unverified, always finish by calling /api/callback/verify with the verifier from the most recent POST you received. An earlier verifier is no longer valid.