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>"}.wordingis required wheneveropted_inis true (a missing one is a422). Leave the object out, or sendopted_in: false, and no contact is created — a license alone never adds anyone to your mailing list. A retried delivery with the sameexternal_referencenever 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.