Webhook v1 en fin de vie ? Testez la migration v1 → v2 côte à côte sur localhost
Webhook v1 étant déprécié ? Faites tourner v1 et v2 côte à côte sur localhost avec des sous-domaines stables, des charges utiles différentes, et suivez une liste de contrôle de bascule sûre.

Quick answer
Webhook v1 Shutdown? Test v1 to v2 Migration on Localhost: quick answer
If free tunnel limits interrupt your workflow, compare session length, stable URLs, concurrent tunnels, and paid-plan pricing before choosing a localhost tunnel tool.
What free tunnel limits should developers check first?
Check session duration, URL stability, concurrent tunnels, custom subdomains, bandwidth or request limits, and whether webhook callbacks survive restarts.
How does InstaTunnel handle longer development sessions?
InstaTunnel Free is designed around 24-hour sessions, with Pro available for higher limits and MCP endpoint tunnel workflows.
Penneo’s legacy webhook service is fully decommissioned on November 30, 2026, which is 14 days from November 16, 2026. After that date, any integration still subscribed through v1 stops receiving events. Qlik is retiring its legacy webhook payload fields on a separate schedule and moving its webhook management API to a new path. GitLab’s own January 2026 planning issue says it has no webhook versioning strategy, so deprecated fields have no removal timeline.
These are three vendors with three different failure modes, and one safe response. Run the old and new webhook paths in parallel against stable URLs on your own machine, capture what each one actually sends, diff the results, and only then cut over. This guide uses two tunnel subdomains, two small receivers, a payload-diff script, a signature verifier and a cutover checklist.
Three webhook deprecations, three different clocks
| Provider | What changes | Date |
|---|---|---|
| Penneo | Legacy (v1) webhook service decommissioned; events stop | Nov 30, 2026 |
| Qlik Cloud | Legacy fields dropped from webhook payloads (hybrid → CloudEvents-only) | Dec 10, 2026 (moved from Oct 6) |
| Qlik Cloud | Legacy identity and access management system events replaced by com.qlik.core.* events |
On or after Nov 30, 2026 |
| Qlik Cloud | /api/v1/webhooks management API removed |
On or after Nov 1, 2027 |
| GitLab | No webhook versioning or removal timeline (per GitLab issue #588235) | Open-ended |
Penneo announced the deprecation on May 21, 2026. Its deprecation overview lists the legacy service as “Deprecated”, which Penneo defines as still functioning but receiving critical and security fixes only. The migration guide says that if you haven’t migrated, you will no longer receive event updates after November 30. It mentions no grace period.
Qlik has the most layered story, and the three changes are easy to confuse:
- Management API path. The
/api/v1/webhooksAPI is deprecated and will be removed on or after November 1, 2027. The replacement lives under/api/core/webhooks. Qlik says both paths use the same webhook resources, so existing webhooks, their IDs and delivery history are preserved, and changing the path does not affect delivery payloads. - Payload format. Qlik announced the move to CloudEvents on September 2, 2025, and has sent hybrid payloads (legacy plus CloudEvents fields) since November 3, 2025. On October 2, 2026 it moved the switch to CloudEvents-only from October 6 to December 10, 2026. Integrations that read
eventId,eventTime,eventType,cloudEventsVersion,contentTypeorextensionsmust move to the CloudEvents equivalents before then. - Event types. Legacy identity and access management system events are deprecated in favor of
com.qlik.core.*events and will be removed on or after November 30, 2026. This notice covers a specific family of events, not everycom.qlik.*type.
One tooling caveat: per Qlik’s November 3, 2026 notice, qlik-cli 3.4.0 and @qlik/api 2.20.0 still call the deprecated /api/v1/webhooks endpoints. Until updated releases ship, scripts built on them need direct REST calls to reach /api/core/webhooks.
GitLab is the cautionary tale. Issue #588235, last edited January 30, 2026 in the version I read, lists four gaps:
- Webhooks carry no version identifier.
- Deprecated fields have no removal timeline.
- Users cannot opt in to test newer formats before changes are enforced.
- Documentation marks fields as deprecated, but they keep being sent.
Some merge request fields have been deprecated since GitLab 8.5, and the issue calls the current additive-only approach “more or less our current status”. Qlik’s REST APIs take the opposite approach. You send a qlik-api-version header, and deprecations come back as deprecation, sunset and link response headers. Qlik also warns that a sunset date is the earliest removal date, not a guaranteed one.
Why side by side beats a big-bang cutover
A changelog tells you what the vendor intends. Captured traffic tells you what actually arrives: headers, field names, types, nesting and retry behavior. Penneo’s guides document endpoints, event types and the signature header, but they do not publish a field-by-field payload diff between v1 and v2. You only learn that by receiving both.
Penneo also states that your endpoint must be publicly accessible and that localhost or private network URLs will not work. A tunnel fills that gap. Stable subdomains matter because you register each callback URL once instead of editing subscriptions every time a random URL changes.
Penneo itself suggests a tool like Webhook.site for a first look at the incoming JSON and headers. That works for a quick check. A local receiver behind a stable subdomain lets you keep raw bodies on disk and replay them against your real handler.
What actually differs between Penneo v1 and v2
| Feature | Legacy (v1) | New (v2) |
|---|---|---|
| Endpoint | {base}/api/v1/webhook |
{base}/webhook/api/v1 |
| Subscribe by | Topics (signer and casefile) | Event types (sign.casefile.completed, sign.signer.signed, …) |
| Confirmation step | Required | Not required |
| Integrity check | Not documented | X-Event-Signature (HMAC-SHA256), optional but recommended |
| Test event | Not documented | webhook.subscription.test |
| Status | Deprecated | Active |
The v2 service documents 17 event types: 4 sign.casefile.* types, 12 sign.signer.* types and the test event. If you subscribed to the “casefile” topic on v1, Penneo says you get the equivalent by subscribing to all four casefile event types. Some signer events can fire more than once if a signer signs in multiple rounds, so don’t treat them as one-shot.
The documented payloads are minimal. A v1-style Sign payload carries a topic, an eventType, an eventTime object and a payload with a numeric ID and status. Penneo notes that notifications are sent for all case files in the account, including ones created by other team members. Your API user may not have permission to fetch details for those, so a super API user may be needed.
Operational limits to design for on v2:
- Your endpoint must accept the connection within 500 ms and respond within 1.5 seconds.
- Only
2xxcounts as success. Any other code, including3xx, triggers a retry. - Delivery is at-least-once.
- Each customer is limited to 5 active subscriptions.
Step 1: Run two receivers behind two stable subdomains
You need a receiver that records everything and answers fast. This one uses only Node’s standard library and writes each request, headers and raw body, to disk. Save it as receiver.mjs.
// receiver.mjs — usage: node receiver.mjs <port> <label>
import http from "node:http";
import { mkdirSync, writeFileSync } from "node:fs";
const [port, label] = [Number(process.argv[2]), process.argv[3]];
mkdirSync(`captures/${label}`, { recursive: true });
http.createServer((req, res) => {
const chunks = [];
req.on("data", (c) => chunks.push(c));
req.on("end", () => {
const raw = Buffer.concat(chunks).toString("utf8");
const file = `captures/${label}/${Date.now()}.json`;
writeFileSync(file, JSON.stringify(
{ method: req.method, url: req.url, headers: req.headers, raw }, null, 2));
res.writeHead(200, { "content-type": "application/json" });
res.end('{"ok":true}');
});
}).listen(port, () => console.log(`${label} listening on ${port}`));
Start one receiver per version, then expose each with its own subdomain. Install the CLI with npm install -g instatunnel. Pick names of your own, since subdomains are unique.
node receiver.mjs 4001 v1 er
node receiver.mjs 4002 v2 er
# in two separate terminals
instatunnel 4001 --subdomain acme-hooks-v1
instatunnel 4002 --subdomain acme-hooks-v2
You now have https://acme-hooks-v1.instatunnel.my and https://acme-hooks-v2.instatunnel.my. The package README describes the free tier as including custom subdomains and three simultaneous tunnels, so two cover the old and new paths and the third stays free for your real application. Other published descriptions of the free tier mention limits on session length, bandwidth and daily requests. Check the current pricing page before you plan a long test around any of these numbers.
Two practical notes:
- The CLI supports a
--passwordflag, but skip tunnel-level password protection on these URLs. Webhook senders generally cannot answer a login prompt. Verify signatures instead. - Your receiver writes its own captures, so you don’t depend on any tunnel-side request log.
Step 2: Point a sandbox subscription at each URL
Use a sandbox or test account, never production. Penneo’s webhook guide links a separate sandbox API reference at sandbox.penneo.com/api/docs. Set PENNEO_BASE_URL to your sandbox base URL.
Start by listing your existing v1 subscriptions with GET {base}/api/v1/webhook/subscriptions. Then point a test v1 subscription at the v1 URL using the deprecated endpoints in the API reference. v1 has a required confirmation step that the migration guide doesn’t spell out. Your first captured v1 request may therefore not be an event at all, which is exactly why you record everything.
Create the v2 subscription next:
curl -X POST "$PENNEO_BASE_URL/webhook/api/v1/subscriptions" \\
-H "Authorization: Bearer $PENNEO_ACCESS_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
"eventTypes": ["sign.casefile.completed", "sign.signer.signed", "webhook.subscription.test"],
"endpoint": "https://acme-hooks-v2.instatunnel.my"
}'
Penneo’s migration guide lists Bearer authorization for both versions. The webhook guide’s example uses a JWT scheme with an X-Auth-Token header and says any supported authorization method works. Use whichever your integration already uses. The response includes the subscription secret, which you need for signature checks. Administrators can also manage subscriptions and review delivery logs in the Penneo UI under Configure → Webhooks.
Trigger the built-in test with POST {base}/webhook/api/v1/subscriptions/test. Then perform the same real action once per version, for example signing a test case file, so both tunnels see equivalent events.
Step 3: Diff the payloads
Comparing a v1 signer event with an unrelated v2 event tells you nothing, so always trigger the same business event on both sides. The script below flattens every captured JSON body into dot-notation paths and reports fields, types and headers that exist on only one side. Save it as diff.mjs.
// diff.mjs — usage: node diff.mjs
import { readdirSync, readFileSync } from "node:fs";
const load = (label) => readdirSync(`captures/${label}`).map((f) =>
JSON.parse(readFileSync(`captures/${label}/${f}`, "utf8")));
function paths(value, prefix = "", out = new Map()) {
if (value !== null && typeof value === "object") {
for (const [k, v] of Object.entries(value)) {
const key = Array.isArray(value) ? "[]" : k;
paths(v, prefix ? `${prefix}.${key}` : key, out);
}
} else out.set(prefix, typeof value);
return out;
}
function shape(label) {
const fields = new Map(), headers = new Set();
for (const c of load(label)) {
Object.keys(c.headers).forEach((h) => headers.add(h));
try { paths(JSON.parse(c.raw), "", fields); } catch { /* non-JSON request */ }
}
return { fields, headers };
}
const report = (title, xs) =>
console.log(`\n${title}\n` + (xs.length ? xs.map((x) => " " + x).join("\n") : " (none)"));
const a = shape("v1"), b = shape("v2");
report("Fields only in v1", [...a.fields.keys()].filter((k) => !b.fields.has(k)));
report("Fields only in v2", [...b.fields.keys()].filter((k) => !a.fields.has(k)));
report("Type changes", [...a.fields].filter(([k, t]) => b.fields.has(k) && b.fields.get(k) !== t)
.map(([k, t]) => `${k}: ${t} -> ${b.fields.get(k)}`));
report("Headers only in v1", [...a.headers].filter((h) => !b.headers.has(h)));
report("Headers only in v2", [...b.headers].filter((h) => !a.headers.has(h)));
Read the output as a migration to-do list:
- Fields only in v1 are things your code may still depend on.
- Headers only in v2 are new capabilities to adopt. The documented signature example lists
x-event-idandx-event-typeamong the signed headers, andx-event-signaturecarries the signature itself. - Type changes are the silent killers. A field that was a number and is now a string passes a schema-less handler and breaks three layers downstream.
Penneo’s documented v2 test event keeps the same topic / eventType / eventTime / payload envelope as the v1 examples, but its payload is a plain text message. It is useful for proving connectivity, but not representative of production events. Expect the most telling differences in headers and delivery behavior rather than in the envelope, and confirm with real events.
The same trick works for Qlik. Capture a hybrid payload, copy it, delete eventId, eventTime, eventType, cloudEventsVersion, contentType and extensions, and replay the copy against your handler. Qlik’s own migration post shows the hybrid event carrying CloudEvents fields (id, time, type) next to the legacy ones, so check which of the two sets your code reads. If the stripped copy still works, you are ready for December 10. If not, you found the bug with weeks to spare.
Step 4: Verify the v2 signature on the raw body
Penneo’s X-Event-Signature header is a comma-separated list of key=value pairs:
tis the Unix timestamp.his a space-separated list of the signed header names.v1is the signature.
A documented example looks like t=1763132484,h=x-event-id x-event-type,v1=abc123....
The signed string is the timestamp, the header-name list, the values of those headers and the raw request body, all joined with dots. The signature is an HMAC-SHA256 hex digest keyed with the subscription secret, compared in constant time. Penneo recommends rejecting timestamps outside a window such as ±5 minutes, and rejecting event IDs you have already processed.
// verify.mjs
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyPenneo(headers, rawBody, secret, toleranceSec = 300) {
const parts = Object.fromEntries(
String(headers["x-event-signature"] ?? "").split(",").map((p) => {
const i = p.indexOf("=");
return [p.slice(0, i).trim(), p.slice(i + 1)];
}));
if (!parts.t || !parts.h || !parts.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSec) return false;
const values = parts.h.split(" ").map((n) => headers[n.toLowerCase()] ?? "");
const signed = [parts.t, parts.h, ...values].join(".") + "." + rawBody;
const expected = createHmac("sha256", secret).update(signed).digest("hex");
const a = Buffer.from(expected), b = Buffer.from(parts.v1);
return a.length === b.length && timingSafeEqual(a, b);
}
Always pass the raw bytes you received, never re-serialized JSON, because whitespace changes break the digest. Also dedupe on X-Event-Id, since delivery is at-least-once. Penneo suggests caching event IDs for a short period, such as the same duration as your timestamp window.
Tunnel gotchas specific to v2
- Answer fast. With a 500 ms connect limit and a 1.5 second response limit, do the minimum in the handler: verify, enqueue, return
2xx. - Never redirect. A
3xxcounts as a failure and is retried, so an HTTP-to-HTTPS or trailing-slash redirect on your endpoint causes retries. - A dead tunnel is not harmless. When a delivery fails, Penneo retries up to 5 times at intervals that start at 5 seconds and grow by 5 seconds each time. It then retries hourly, up to 30 times. After all 35 retries it stops and automatically disables the subscription, then emails the user who created it and the customer’s administrators. By my arithmetic from that schedule, that is roughly 30 hours after the first failure. A sandbox subscription left pointing at a stopped tunnel over a long weekend will be switched off, and someone must manually update and re-enable it.
- Watch your tunnel’s session limits. If your tunnel plan caps session length, a tunnel that drops and returns on a new connection can leave you debugging missed deliveries. Check your plan’s limits and use the delivery logs under Configure → Webhooks.
- Mind the five-subscription cap. The cap is documented as 5 active subscriptions per customer on the new service. The docs don’t say whether old v1 subscriptions count, so don’t assume headroom while both versions run.
The cutover checklist
- Inventory every v1 subscription (
GET {base}/api/v1/webhook/subscriptions) and every code path that calls/api/v1/webhook. - Map each v1 topic to v2 event types. For example, “casefile” maps to the four
sign.casefile.*types, and signer notifications map to the relevantsign.signer.*types. - Create the v2 test subscription, fire
webhook.subscription.test, and confirm receipt on the v2 tunnel. - Capture the same real events on both tunnels and run
diff.mjs. Fix every field, type and header difference. - Add signature verification and
X-Event-Ididempotency to the v2 handler. - Acknowledge first. Move slow work behind a queue so responses stay inside 1.5 seconds.
- Create the production v2 subscription at
{base}/webhook/api/v1. Keep the overlap short, since both versions firing means duplicate notifications. - Delete the old subscriptions with
DELETE {base}/api/v1/webhook/subscriptions/{subscriptionId}once v2 traffic is confirmed. - Watch delivery logs (Configure → Webhooks in Penneo) for a few days, then release the tunnel subdomains you no longer use.
- Repeat for Qlik and GitLab, as described below.
Qlik: three changes, three tests
1. Management API path (by November 2027). The migration is mechanical. Replace /api/v1/webhooks with /api/core/webhooks and keep the rest of the path, query parameters and request bodies unchanged. Qlik’s notice lists ten direct endpoint replacements, covering list, create, get, patch, put, delete, deliveries, delivery details, resend and event types. Test in a non-production tenant first.
2. Payload format (December 10, 2026). Use the stripped-payload replay from Step 3. Qlik documents CloudEvents-only payloads from that date.
3. System event types (on or after November 30, 2026). If your subscription uses a legacy identity and access management event, swap in the mapped com.qlik.core.* type. Some mappings rename more than the prefix:
| Legacy event type | Replacement |
|---|---|
com.qlik.v1.user.created |
com.qlik.core.user.created |
com.qlik.user-session.begin |
com.qlik.core.user-session.begun |
com.qlik.group.config.updated |
com.qlik.core.group-setting.updated |
Qlik says that only com.qlik.v1.user.created, com.qlik.v1.user.deleted and com.qlik.v1.api-key.validation.failed from that notice are available through Qlik Cloud Webhooks. During any overlap period, deduplicate events using the CloudEvent id to avoid processing the same change twice.
Qlik’s versioning policy (a qlik-api-version header with quarterly YYYY-MM releases, each supported for 12 months) governs REST APIs. System events do not use the header. Their deprecations are documented in the AsyncAPI specs, so read those specs, not just response headers.
GitLab: build your own versioning
Since GitLab offers no opt-in preview, make your own. Save real payloads as fixtures and diff them whenever you upgrade GitLab. For merge request webhooks, issue #588235 lists these deprecated fields and their replacements:
| Deprecated | Use instead |
|---|---|
repository (top-level) |
project |
labels (top-level) |
object_attributes.labels |
project.http_url |
project.git_http_url |
project.homepage |
project.web_url |
project.ssh_url |
project.git_ssh_url |
project.url |
project.git_ssh_url or project.git_http_url |
object_attributes.assignee_id |
object_attributes.assignee_ids |
object_attributes.work_in_progress |
object_attributes.draft |
None of these has a removal date. Moving off them now means you won’t be surprised if GitLab adopts a removal policy later. The same issue floats options such as versioned webhooks and deprecation-with-timeline, but none is committed.
Frequently asked questions
What happens to Penneo webhooks after November 30, 2026? Subscriptions on the legacy service stop delivering events. Migrate to the v2 service at {base}/webhook/api/v1 first.
Do I need a public URL to test webhooks locally? Yes. Penneo says localhost and private network URLs will not work, so use an HTTPS tunnel with a stable subdomain.
Is Qlik’s November 2027 date the only deadline? No. That date covers the /api/v1/webhooks management API. Legacy payload fields go on December 10, 2026, and the legacy identity and access management system events are removed on or after November 30, 2026.
Will Qlik’s webhook path change break my existing webhooks? According to Qlik, no. Existing webhooks, IDs and delivery history are preserved, and the path change does not affect delivery payloads.
How many tunnels do I need? Two for a side-by-side test, one per payload version. A third lets you keep your own app reachable at the same time, if your plan allows three simultaneous tunnels.
Sources
- Migration guide: Webhook deprecation (Penneo)
- Webhooks guide (Penneo)
- Deprecation overview (Penneo)
- Webhooks API deprecated in favor of Core webhooks API (Qlik)
- Webhooks legacy event fields removal (Qlik)
- Legacy identity and access management system events deprecation (Qlik)
- Qlik Cloud Webhooks: Migration to new event formats (Qlik Community)
- Qlik API versioning and deprecation headers
- Investigate and plan webhook versioning and deprecation strategy (GitLab #588235)
- instatunnel CLI README (Pkg Stats)
Related InstaTunnel pages
Continue from this article into the most relevant product guides and workflows.
Related Topics
Keep building with InstaTunnel
Read the docs for implementation details or compare plans before you ship.