Skip to Content
LicensingTroubleshooting

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:

  1. X-Appneck-Product doesn’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.
  2. No webhook secret has been generated for this product yet, or it was revoked. Generate one from Licensing → Store Integration.
  3. X-Appneck-Timestamp is 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).
  4. X-Appneck-Signature header is missing entirely — often a copy-paste that dropped one header.
  5. 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, not raw_body . timestamp or 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_name missing, or plan_name doesn’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-connection returns for the same cause.
  • marketing_consent.opted_in is true but marketing_consent.wording is 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_email present 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.