Set up webhooks

Receive signed notifications on your backend when licenses or devices change.

What you will learn

• Add and test an HTTPS endpoint from your workspace.
• Separate Sandbox and Live deliveries.
• Pause delivery and coordinate signing-secret replacement.

Prerequisites

• A workspace and product with available webhook allowance.
• An HTTPS backend URL with a valid certificate and public DNS/IP address.
• A receiver that reads raw request bytes and verifies HMAC signatures.
• A server-side secret store outside your public web directory.

Decide what the endpoint does

Use notifications for activity views, support alerts, reconciliation and your own background workflows. Never unlock an application solely because a license.created or license.restored notification arrived. For application access, use the activation and validation flow and verify its signed response.

This guide covers KDPika Licensing sending events to you. A store integration runs in the other direction: your backend receives the store's authenticated payment event and calls the licensing API. The two endpoint secrets and verification algorithms are not interchangeable.

Create an endpoint

1. Sign in to your workspace and select Sandbox in the environment control.
2. Open Webhooks in the sidebar.
3. Select Add endpoint.
4. Enter your final HTTPS endpoint URL, without a redirect, URL credentials or a secret query parameter.
5. Select one product or All products.
6. Select the events your handler implements from the event catalog.
7. Select Create endpoint.
8. Copy the displayed Webhook signing secret into your backend's secret store immediately.
9. Pin that receiver to the sandbox envelope environment.

Expected result: the endpoint appears as Active and the secret is shown once. The secret cannot be displayed again after that flash message is consumed; rotate it if you lost it. The new-endpoint dialog initially selects license.created, license.activated and license.revoked; choose deliberately rather than relying on those defaults.

The URL is limited to 2048 characters. Private, loopback, reserved-IP, credential-bearing and redirecting targets cannot be used for platform delivery. You can update an endpoint URL with Update in its row. Already queued deliveries retain their original event IDs and are sent to the current URL at their next attempt. There is no general public REST endpoint for administering webhook endpoints.

Test the connection

1. Keep the endpoint Active.
2. Select Send test in its row.
3. Find test.ping and its event ID in Delivery history.
4. Confirm your receiver authenticated the exact bytes and durably recorded that event ID.
5. Check the history row for a 2xx response and Delivered status.

Expected result: test.ping arrives without creating a license, charging a payment or consuming an installation. Send test can target the endpoint even if test.ping was not selected among its business events. If the endpoint is disabled, the test can be queued but no network attempt occurs yet. A confirmation saying sent or queued is not proof of receipt.

Separate environments

Create separate endpoint records and secrets for Sandbox and Live. Ordinary event routing matches the endpoint's organization, environment, product scope and selected event names. Do not infer the environment from a hostname or a key prefix alone; verify the signed environment value as well.

A Free workspace is for Sandbox evaluation. A webhook notification does not grant Live access or bypass platform limits. Before enabling Live, run the go-live checklist.

Disable and enable

1. Select Disable in the endpoint row before maintenance.
2. Confirm the endpoint status becomes Disabled.
3. Finish your receiver maintenance.
4. Select Enable.
5. Inspect remaining queued deliveries and retry eligible failed rows when necessary.

Expected result: existing queued rows are retained and attempts are skipped while disabled; attempts are not incremented by those skips. Ordinary events published while disabled are not queued for that endpoint. Enabling is not a historical backfill. A previously delivered row does not send again. See delivery limits before relying on Retry.

Rotate a signing secret

1. Prepare a secure way to update the receiver's secret configuration.
2. Disable the Sandbox endpoint to reduce new attempts during the change.
3. Select Rotate and confirm replacement.
4. Copy the new one-time secret into your receiver configuration.
5. Reload the receiver using your normal secure deployment process.
6. Enable the endpoint.
7. Send test and confirm authenticated receipt.
8. Remove retired receiver credentials after accounting for any request already in flight.

Expected result: new attempts use the replacement secret. Rotation takes effect immediately on the sender, including queued events. There is no automatic old/new overlap, secret-version header or two-active-secret rotation API. A request already sent before rotation may still be in flight; coordinate that window and use durable deduplication. The temporary pause does not queue business events published while disabled, so reconcile any gap from your own backend records.

Expected result

Your backend receives only its configured notifications, rejects invalid signatures and environments, records authenticated event IDs durably and does not treat them as application license authorization.

Common mistakes

• Putting a developer API key or endpoint signing secret in a desktop executable or browser application.
• Using a Stripe signing secret for a KDPika Licensing notification.
• Treating Enable as a replay of all events missed while disabled.
• Assuming Send test bypasses Disabled status.

Security notes

Use one endpoint secret per record. Do not log the secret, complete signature header, license key or full customer payload. No fixed outbound IP range is published here; authenticate the signature instead of inventing an IP allowlist. Keep your own event log private and apply a justified retention policy.

Troubleshooting

Next steps

Read the full event catalog, then implement delivery handling.

Related

• Verify webhook signatures
• Test webhooks locally
• Webhook security