Skip to Content
LicensingStore Integration

Store integration

Every store integration reduces to the same request: your store calls one webhook when a sale completes, signed with a secret only you and Appneck know, and gets a license key back. This page has one worked example per platform. If you haven’t called the webhook at all yet, start with Testing your integration instead — proving the secret works with a single curl command first makes every one of these examples easier to debug if something’s wrong.

What every example does the same way

  • Signature: hash_hmac('sha256', timestamp . '.' . raw_body, secret) — the timestamp joined to the exact bytes of the request body with a literal .. Sign the same string you send; re-encoding the body between signing and sending is the single most common way to produce a signature that looks right and isn’t.
  • Headers: X-Appneck-Product (your product’s slug), X-Appneck-Timestamp (current Unix time, in seconds), X-Appneck-Signature (the hex HMAC above).
  • external_reference: always send your own order/subscription id. It’s how Appneck recognises a retried delivery as the same sale — every store retries a slow or dropped response eventually, and without this field a retry issues a second license for one purchase.
  • marketing_consent (optional): only when the buyer ticked an email opt-in at checkout, send "marketing_consent": {"opted_in": true, "wording": "<the exact text they saw>", "ip": "<optional>"}. wording is required whenever opted_in is true (a missing one is a 422). Leave the object out, or send opted_in: false, and no contact is created — a license alone never adds anyone to your mailing list. A retried delivery with the same external_reference never records the consent a second time.
  • Failures are logged, not swallowed. A webhook call that never reaches Appneck (DNS hiccup, timeout) should end up somewhere you’ll see it, not silently disappear — your platform’s own error log is enough.
  • The returned license key is surfaced, not discarded — emailed to the customer, or at minimum stored where support can find it against the order.

A1 — WooCommerce

Hooked on order completion. Handles multi-item orders (one order, several licenses) and variations (one product with Single Site / 5 Sites / Unlimited variations mapping to three different Plans by name). Verified against the dev backend: a simulated 3-item order with three different variations produced three real 201s, one license per plan.

<?php /** * functions.php or a small must-use plugin. * Fires once, when an order moves to "completed" — after payment clears, * not at checkout — so a license is never issued for an order that later * fails payment. */ add_action('woocommerce_order_status_completed', 'appneck_issue_licenses_for_order'); function appneck_issue_licenses_for_order(int $order_id): void { $order = wc_get_order($order_id); if (! $order) { return; } $issued_keys = []; foreach ($order->get_items() as $item_id => $item) { $product = $item->get_product(); if (! $product || ! appneck_is_licensed_product($product)) { continue; } // One line item can be multiple quantity — issue one license per unit. for ($unit = 1; $unit <= $item->get_quantity(); $unit++) { $plan_name = appneck_plan_name_for_variation($product); $reference = "wc-order-{$order_id}-item-{$item_id}-{$unit}"; $result = appneck_call_webhook($plan_name, $order, $reference); if ($result === null) { // Logged inside appneck_call_webhook(); do not silently // skip the customer's email — surface that something // needs manual attention. $order->add_order_note("Appneck: failed to issue a license for item {$item_id} — check the error log."); continue; } $issued_keys[] = $result['license_key']; // Stored on the order so support can find it without asking // the customer to dig up an email. $order->add_meta_data('_appneck_license_key_' . $item_id . '_' . $unit, $result['license_key'], true); } } if ($issued_keys) { $order->add_order_note('Appneck license key(s) issued: ' . implode(', ', $issued_keys)); $order->save(); } } /** * The variation's own attribute value IS the plan name — "Single Site", * "5 Sites", "Unlimited" — matched exactly against a Plan you created in * Licensing → Plans. A simple product with no variations falls back to * the product name itself. */ function appneck_plan_name_for_variation(\WC_Product $product): string { if ($product->is_type('variation')) { $attributes = $product->get_variation_attributes(); $license_attribute = $attributes['attribute_license-tier'] ?? reset($attributes); if ($license_attribute) { return $license_attribute; } } return $product->get_name(); } function appneck_is_licensed_product(\WC_Product $product): bool { // Tag the products that should issue licenses however suits your // catalog — a product meta flag, a category, a SKU prefix. return $product->get_meta('_appneck_licensed') === 'yes'; } /** @return array{license_key: string, expires_at: ?string, activation_limit: ?int, plan_name: string}|null */ function appneck_call_webhook(string $plan_name, \WC_Order $order, string $reference): ?array { $secret = defined('APPNECK_WEBHOOK_SECRET') ? APPNECK_WEBHOOK_SECRET : getenv('APPNECK_WEBHOOK_SECRET'); $slug = 'your-product-slug'; // your product's slug, from Store Integration $body = wp_json_encode([ 'plan_name' => $plan_name, 'customer_name' => $order->get_formatted_billing_full_name(), 'customer_email' => $order->get_billing_email(), 'external_reference' => $reference, ]); $timestamp = (string) time(); $signature = hash_hmac('sha256', $timestamp . '.' . $body, $secret); $response = wp_remote_post('https://appneck.com/webhooks/v1/licenses/issue', [ 'headers' => [ 'Content-Type' => 'application/json', 'X-Appneck-Product' => $slug, 'X-Appneck-Timestamp' => $timestamp, 'X-Appneck-Signature' => $signature, ], 'body' => $body, 'timeout' => 10, ]); if (is_wp_error($response)) { error_log('Appneck webhook transport error: ' . $response->get_error_message()); return null; } $status = wp_remote_retrieve_response_code($response); $data = json_decode(wp_remote_retrieve_body($response), true); if ($status >= 400) { error_log("Appneck webhook returned {$status}: " . wp_remote_retrieve_body($response)); return null; } // already_issued (a retried delivery) carries no license_key — that's // expected, not an error; the first successful call already has it. if (! isset($data['license_key'])) { return null; } return $data; }

The secret belongs in wp-config.php, not in this file: define('APPNECK_WEBHOOK_SECRET', 'whsec_…'); above the /* That's all, stop editing! */ line, or in your host’s environment variables — never committed alongside plugin code.

A2 — Easy Digital Downloads

Same signature and headers as WooCommerce; the differences are EDD’s own hook and its price-variation model (multiple prices per download, rather than WooCommerce’s product-variation attributes). Verified against the dev backend with a real 201.

<?php /** * Fires once per completed payment. edd_get_payment_meta_downloads() * gives you every download in the cart, each with its own price_id when * the download has price variations. */ add_action('edd_complete_purchase', 'appneck_issue_licenses_for_payment', 10, 1); function appneck_issue_licenses_for_payment(int $payment_id): void { $downloads = edd_get_payment_meta_downloads($payment_id); $email = edd_get_payment_user_email($payment_id); $name = edd_get_payment_meta($payment_id, '_edd_payment_meta', true)['user_info']['first_name'] ?? ''; if (! is_array($downloads)) { return; } foreach ($downloads as $download) { if (! appneck_download_is_licensed((int) $download['id'])) { continue; } $price_id = $download['options']['price_id'] ?? null; $plan_name = $price_id !== null ? edd_get_price_option_name((int) $download['id'], (int) $price_id) : get_the_title((int) $download['id']); $reference = "edd-payment-{$payment_id}-{$download['id']}" . ($price_id !== null ? "-{$price_id}" : ''); $result = appneck_call_webhook($plan_name, $name, $email, $reference); if ($result === null) { edd_insert_payment_note($payment_id, "Appneck: failed to issue a license for download {$download['id']} — check the error log."); continue; } edd_insert_payment_note($payment_id, "Appneck license key issued: {$result['license_key']}"); edd_update_payment_meta($payment_id, '_appneck_license_key_' . $download['id'], $result['license_key']); } } function appneck_download_is_licensed(int $download_id): bool { return get_post_meta($download_id, '_appneck_licensed', true) === 'yes'; } /** @return array{license_key: string, expires_at: ?string, activation_limit: ?int, plan_name: string}|null */ function appneck_call_webhook(string $plan_name, string $customer_name, string $customer_email, string $reference): ?array { $secret = defined('APPNECK_WEBHOOK_SECRET') ? APPNECK_WEBHOOK_SECRET : getenv('APPNECK_WEBHOOK_SECRET'); $slug = 'your-product-slug'; $body = wp_json_encode([ 'plan_name' => $plan_name, 'customer_name' => $customer_name, 'customer_email' => $customer_email, 'external_reference' => $reference, ]); $timestamp = (string) time(); $signature = hash_hmac('sha256', $timestamp . '.' . $body, $secret); $response = wp_remote_post('https://appneck.com/webhooks/v1/licenses/issue', [ 'headers' => [ 'Content-Type' => 'application/json', 'X-Appneck-Product' => $slug, 'X-Appneck-Timestamp' => $timestamp, 'X-Appneck-Signature' => $signature, ], 'body' => $body, 'timeout' => 10, ]); if (is_wp_error($response)) { error_log('Appneck webhook transport error: ' . $response->get_error_message()); return null; } $status = wp_remote_retrieve_response_code($response); $data = json_decode(wp_remote_retrieve_body($response), true); if ($status >= 400 || ! isset($data['license_key'])) { if ($status >= 400) { error_log("Appneck webhook returned {$status}: " . wp_remote_retrieve_body($response)); } return null; } return $data; }

A3 — Node / serverless (Shopify, Gumroad, Lemon Squeezy, Paddle)

All four reduce to the identical shape once you’ve received their webhook: verify their signature (each platform has its own — check their docs), extract a plan name and an order id from their payload, then call Appneck’s webhook with Appneck’s signature. Verified against the dev backend with a real 201 (Node, using the built-in fetch and crypto, no dependencies).

const crypto = require('crypto'); const APPNECK_SECRET = process.env.APPNECK_WEBHOOK_SECRET; // never hardcode this const APPNECK_SLUG = 'your-product-slug'; async function issueAppneckLicense({ planName, customerName, customerEmail, externalReference }) { const body = JSON.stringify({ plan_name: planName, customer_name: customerName, customer_email: customerEmail, external_reference: externalReference, }); const timestamp = String(Math.floor(Date.now() / 1000)); const signature = crypto .createHmac('sha256', APPNECK_SECRET) .update(timestamp + '.' + body) .digest('hex'); const response = await fetch('https://appneck.com/webhooks/v1/licenses/issue', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Appneck-Product': APPNECK_SLUG, 'X-Appneck-Timestamp': timestamp, 'X-Appneck-Signature': signature, }, body, }); const data = await response.json(); if (!response.ok) { // Logged, not swallowed — a store's own webhook handler usually gets // one retry from the platform, so throwing here is often enough; add // your platform's logger if you have one. console.error(`Appneck webhook returned ${response.status}:`, data); throw new Error('Appneck license issuance failed'); } return data; // { license_key, expires_at, activation_limit, plan_name } — or already_issued: true on a retry } // Deriving plan_name / external_reference differs per platform — // everything past this point is the one part that isn't universal. function fromShopify(order) { // Shopify: line_items[].variant_title carries the tier if you use // variants for it; order.id is the order id. const item = order.line_items[0]; return { planName: item.variant_title || item.title, customerName: `${order.customer.first_name} ${order.customer.last_name}`, customerEmail: order.email, externalReference: `shopify-${order.id}`, }; } function fromGumroad(sale) { // Gumroad: `variants` is a string like "Tier: Agency"; `sale_id` is // the order id. const tier = (sale.variants || '').split(':').pop()?.trim() || sale.product_name; return { planName: tier, customerName: sale.full_name, customerEmail: sale.email, externalReference: `gumroad-${sale.sale_id}`, }; } function fromLemonSqueezy(event) { // Lemon Squeezy: variant_name is the plan tier; order_id is the order. const attrs = event.data.attributes; return { planName: attrs.variant_name, customerName: attrs.user_name, customerEmail: attrs.user_email, externalReference: `lemonsqueezy-${event.data.id}`, }; } function fromPaddle(event) { // Paddle (v2 webhooks): items[].price.description or a custom field // you set on the price; the transaction id is the order id. const item = event.data.items[0]; return { planName: item.price.description, customerName: event.data.customer.name, customerEmail: event.data.customer.email, externalReference: `paddle-${event.data.id}`, }; } module.exports = { issueAppneckLicense, fromShopify, fromGumroad, fromLemonSqueezy, fromPaddle };

A4 — Laravel / generic PHP

For an org running its own store rather than a WordPress plugin marketplace. Framework-light on purpose — hash_hmac() and curl/Http are the only requirements, so this adapts to whatever the checkout code already is. Verified against the dev backend with a real 201.

<?php function appneck_issue_license(object $order, string $planName): ?array { $secret = env('APPNECK_WEBHOOK_SECRET'); // .env, never committed $slug = 'your-product-slug'; $body = json_encode([ 'plan_name' => $planName, 'customer_name' => $order->customer_name, 'customer_email' => $order->customer_email, 'external_reference' => (string) $order->id, ]); $timestamp = (string) time(); $signature = hash_hmac('sha256', $timestamp . '.' . $body, $secret); // Using Laravel's Http facade — a plain curl_exec() works identically // if you're not on Laravel; only the transport call changes. $response = \Illuminate\Support\Facades\Http::withHeaders([ 'Content-Type' => 'application/json', 'X-Appneck-Product' => $slug, 'X-Appneck-Timestamp' => $timestamp, 'X-Appneck-Signature' => $signature, ])->withBody($body, 'application/json') ->timeout(10) ->post('https://appneck.com/webhooks/v1/licenses/issue'); if ($response->failed()) { \Illuminate\Support\Facades\Log::error('Appneck webhook failed', [ 'status' => $response->status(), 'body' => $response->json(), ]); return null; } return $response->json(); // license_key, expires_at, activation_limit, plan_name }

A5 — curl (verify the secret before writing any code)

The single most valuable example on this page — it proves your webhook secret is correct in one copy-pasteable command, with no code to write or debug. See Testing your integration for the full command, run live against a real backend with its actual output.