Troubleshooting
Every response the store webhook (POST /webhooks/v1/licenses/issue, and the identically-authenticated
/webhooks/v1/licenses/test-connection) can return, in order of how likely you are to hit it during setup.
401 Unauthorized — {"message":"Unauthorized."}
Deliberately the same message for five different causes — a real security boundary, not a missing detail: if the response said which check failed, an attacker could use that to work out whether a product slug or a secret is valid one guess at a time. All five are equally likely early on, so check them in this order:
X-Appneck-Productdoesn’t match any product’s slug — check for a typo, and confirm you’re using the slug (from the product’s page in the org panel), not its display name.- No webhook secret has been generated for this product yet, or it was revoked. Generate one from Licensing → Store Integration.
X-Appneck-Timestampis missing, isn’t a plain integer, or is too far from the current time — check your server’s clock is correct, and that you’re sending Unix seconds (not milliseconds — a millisecond value is ~1000x too large and will always look stale).X-Appneck-Signatureheader is missing entirely — often a copy-paste that dropped one header.- The signature doesn’t match — by far the most common in practice. Check, in order:
- You’re signing the exact bytes of the body you send — encode the JSON once, sign that string, send that same string. Re-encoding between signing and sending (even producing “the same” JSON) changes whitespace/key order enough to break the signature.
- The formula is
timestamp . '.' . raw_body— timestamp first, joined with a literal dot, notraw_body . timestampor a JSON-wrapped combination. - You’re using the current secret — a Regenerate replaces it immediately; old signed requests start failing the instant that happens.
- You copied the whole secret, including the
whsec_prefix.
If you’re not sure which of these five it is, use the curl command in
Testing your integration with values you know are correct,
then change one thing at a time (wrong secret on purpose, wrong slug on purpose) to see what a real failure
looks like — every case above produces the identical response, so there’s nothing more specific to
discover from the error itself.
403 Forbidden
Two causes, each with its own distinct message — these are not part of the five above, because they confirm the secret and signature were both correct; this is “you’re not allowed in right now,” not “who are you”:
{"message":"This organization's account is suspended."}— the organization’s account is suspended. Contact Appneck.{"message":"This product has been archived."}— the product itself has been archived in the org panel.
422 Unprocessable Content
Standard Laravel validation shape: {"message": "...", "errors": {"field": ["..."]}}.
plan_namemissing, orplan_namedoesn’t match any active Plan for this product — check for an exact spelling/case match against Licensing → Plans; an archived Plan doesn’t count either. This is the same 422 (and the same message)test-connectionreturns for the same cause.marketing_consent.opted_inis true butmarketing_consent.wordingis missing or empty. Consent without the exact wording the buyer saw can’t be recorded, so the request is refused rather than guessed at.customer_emailpresent but not a valid email address.- Any field over its length limit (
customer_name/customer_email/external_reference, each 255 characters).
429 Too Many Requests
Rate limited — 120 requests/minute per product for the real issuance endpoint, a separate 30/minute budget
for test-connection (exhausting one never affects the other). A legitimate integration issuing licenses
one at a time as sales complete should never come close to this; hitting it usually means a retry loop is
firing far faster than intended. Back off and retry after a few seconds.
Transport failures (no HTTP response at all)
DNS failure, connection refused, timeout — your code never got a response to parse. This is not something
Appneck returns; it’s what your own HTTP client reports (a WP_Error from wp_remote_post(), a rejected
promise from fetch, a thrown ConnectionException). Every example in
Store integration logs this case explicitly rather than treating a
null/failed response as “nothing happened” — check your own error log first when a sale doesn’t produce a
license and none of the statuses above showed up anywhere.
A retried delivery didn’t return a license key
Expected, not a bug: a 200 with "already_issued": true and no license_key means this
external_reference was already used successfully. The key was returned on the first successful call
— if you didn’t capture it then, it cannot be retransmitted; issue a new license by hand from the org panel
for this customer instead.