ZIPPY DOCS

Webhooks

Get an HTTP ping when a link is created, updated, or archived — and when someone actually opens your app from a link. Connect Zippy to n8n, Zapier, Make, or anything with a URL.

Webhooks

Webhooks push Zippy events to any HTTPS URL you own, the moment they happen. Two kinds of signal ride the same stream:

  • Link lifecycle — a link was created, updated, or archived.
  • App-open outcomes — someone tapped your link and Zippy tells you what actually happened on their device: the real app opened, they stayed in the browser, or the hand-off broke. No other link tool exports this signal.

That second one is the point. Click counts tell you a tap happened; the app-open stream tells you whether the tap worked — per link, per platform, per country, in real time, delivered to your own systems.

Webhooks are a Legend power.

Set it up

  1. In the dashboard, open Webhooks and add an endpoint: a public https:// URL you control, plus the events you want (any mix of the six below).
  2. Zippy shows you the endpoint's signing secret exactly once, at creation. Store it — it can't be read back later. (Lost it? Delete the webhook and register a new one.)
  3. Done. Deliveries start immediately. You can pause an endpoint (active: off), change its URL or event list, or delete it anytime. An org can register up to 5 webhooks.

The delivery

Every event is a POST to your URL with a JSON body and two headers:

POST https://your-server.example/zippy
content-type: application/json
x-zippy-event: app.opened
x-zippy-signature: 7f8a1c…   (hex HMAC-SHA256 of the raw body)

The body is always the same envelope:

{
  "event": "app.opened",
  "ts": "2026-07-19T14:03:22.512Z",
  "data": { … }
}

The seven events

link.created · link.updated · link.archived

Fired when a link is made, edited, or archived — from the dashboard, the mobile app, or the API. data is the link object, the same shape the API returns:

{
  "event": "link.created",
  "ts": "2026-07-19T14:01:09.104Z",
  "data": {
    "id": "lnk_9f2c…",
    "slug": "summer-drop",
    "hostname": null,
    "destination": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "platformKey": "youtube",
    "branded": false,
    "readOnly": false,
    "utm": { "source": "instagram", "campaign": "summer_drop" },
    "routing": null,
    "hasPassword": false,
    "tags": ["launch", "summer"],
    "folderId": null,
    "pixelIds": [],
    "createdAt": "2026-07-19T14:01:09.062Z",
    "updatedAt": "2026-07-19T14:01:09.062Z"
  }
}

app.opened · app.browser · app.broken

Fired when a visitor taps one of your links and the device reports back what happened:

  • app.opened — the native app actually opened. The tap worked.
  • app.browser — the visitor stayed in the (in-app) browser.
  • app.broken — the hand-off failed (e.g. an intent fired into a void).

data carries the tap's context:

{
  "event": "app.opened",
  "ts": "2026-07-19T14:03:22.512Z",
  "data": {
    "slug": "summer-drop",
    "shortHost": "zipthe.link",
    "platformKey": "youtube",
    "sourceApp": "instagram",
    "country": "US",
    "city": "Austin",
    "device": "ios",
    "ts": "2026-07-19T14:03:21.900Z"
  }
}

sourceApp is where the tap came from (the in-app browser it escaped), platformKey is the app the link targets, and the context fields are null when a device doesn't report them. The outer ts is delivery time; data.ts is when the tap happened.

contact.captured

Fired when a visitor hands you their email through the rich fallback page's "Get updates from this creator" form (a Hero+ power — see email capture). Fires once per new contact; a re-submit of an email already on your list is a no-op and sends nothing.

{
  "event": "contact.captured",
  "ts": "2026-07-19T14:05:40.318Z",
  "data": {
    "email": "[email protected]",
    "sourceSlug": "summer-drop",
    "country": "US",
    "createdAt": "2026-07-19T14:05:40.301Z"
  }
}

The email is included: it's your own audience data going to your own endpoint, so you can pipe new contacts straight into your CRM or ESP. country is best-effort (from the edge geo header) and null when unknown. You are the data controller for these emails — send only what your consent copy promised. See email capture for the consent record we store and your obligations as the data controller.

Verify the signature

Every delivery is signed so your receiver can be sure it came from Zippy and wasn't tampered with. x-zippy-signature is the hex HMAC-SHA256 of the raw request body, keyed with your endpoint's signing secret. Verify it before trusting the payload:

import { createHmac, timingSafeEqual } from "node:crypto";
 
function verify(rawBody, signatureHeader, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

Compute the HMAC over the raw body bytes — parse the JSON only after the signature checks out. If your framework parses the body for you, grab the raw string first (most have a "raw body" option for exactly this).

Delivery is single-attempt

Zippy delivers each event once, with a 5-second timeout. There's no retry queue: if your endpoint is down or slow, that delivery is missed and the endpoint's fail counter ticks up (you'll see it in the dashboard; any successful delivery resets it). Treat the stream as a live signal, not a ledger — keep your receiver fast (respond 2xx before doing heavy work) and watch the fail count.

Use it with n8n / Zapier / Make

No code needed — both tools have a "catch a webhook" trigger, and Zippy speaks it natively. Here's the classic: a Google Sheets row for every real app-open.

Zapier

  1. Create a Zap with the Webhooks by Zapier trigger, event Catch Hook. Zapier gives you a URL.
  2. In Zippy's Webhooks page, register that URL and pick app.opened (add app.browser / app.broken too if you want the misses).
  3. Tap one of your links from a phone so Zapier catches a sample, then map the fields — data.slug, data.platformKey, data.sourceApp, data.country, data.device, data.ts — into a Google Sheets → Create Spreadsheet Row action.
  4. Turn the Zap on. Every real app-open lands in your sheet as it happens.

Make

  1. Add a Webhooks → Custom webhook module; copy its URL.
  2. Register that URL in Zippy with the events you want.
  3. Tap a link once so Make learns the payload shape, then chain any module — add a Sheets row, post to Slack, fire a Discord message, update Airtable.

n8n

  1. Add a Webhook node (method POST) and copy its production URL, with Raw Body switched on so you can verify the signature.
  2. Register that URL in Zippy with the events you want.
  3. Check the HMAC in a Code node (see Verify the signature), then branch with an IF or Switch node on event.

Full walkthrough, plus making links mid-workflow: n8n + Zippy.

Same recipe, any direction: ping a Slack channel when app.broken spikes, tag a CRM contact by country, or log every link.created for a team audit trail. If it has a catch-webhook trigger, Zippy can feed it.

Notes

  • Endpoints must be public https URLs — no plain http, no localhost or private addresses. For local testing, use a tunnel (e.g. cloudflared or ngrok) or a bin service like webhook.site.
  • One event, many endpoints: if several webhooks subscribe to the same event, they all get it.
  • The app-open outcomes are the same signal that powers your click analytics — webhooks just export it. See audience routing and the UTM builder for what rides along on the link itself.
  • Prefer a canvas to a curl? n8n + Zippy wires this whole page into a workflow, and the API is the pull-side counterpart. ManyChat uses the same events to answer "did my DM taps reach the app?", and so do Instagram DM automations.

Read more

Previous

Deep Link Debugger

Next

API

On this page