Webhooks & Event Delivery API

Taqlyn delivers real-time notifications to your webhooks whenever links are created, clicked, or matched on a mobile device.

#Supported Webhook Events

Event Type	Trigger
`link.created`	A new short link was generated via the API or dashboard.
`link.clicked`	An end-user visited a link on web, iOS, or Android.
`link.resolved`	A deferred link was successfully matched and consumed by a mobile app.
`app.bound`	Platform settings (iOS team ID or Android fingerprints) were updated.

#Webhook Delivery Payload

Every webhook POST delivers an event envelope in JSON format:

JSON

{
  "id": "evt_981240cafe",
  "type": "link.resolved",
  "createdAt": "2026-09-05T12:05:30Z",
  "appId": "app_live_8f92ab140cd3",
  "data": {
    "linkId": "sl_9128abef",
    "shortUrl": "https://taqlyn.com/summer24",
    "destinationPath": "/products/491",
    "params": {
      "sku": "491",
      "promo": "SUMMER",
      "referrer": "influencer_mike"
    },
    "matchedVia": "clipboard",
    "platform": "ios"
  }
}

#Verifying Webhook Signatures

To ensure payloads originate from Taqlyn and have not been altered, Taqlyn signs the raw request body with your webhook endpoint secret using HMAC-SHA256:

HTTP

X-Taqlyn-Webhook-Signature: t=1725537930,v1=9fa8102bca4810beef...

#Signature Verification (Node.js)

TypeScript

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWebhook(
  rawBody: string | Buffer,
  header: string,
  secret: string
): boolean {
  const parts = Object.fromEntries(
    header.split(",").map((kv) => kv.split("="))
  );
  
  const timestamp = parts["t"];
  const signature = parts["v1"];
  if (!timestamp || !signature) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  return timingSafeEqual(Buffer.from(signature, "hex"), Buffer.from(expected, "hex"));
}

#Retry Policy & Timeouts

Timeout: Your webhook receiver must respond with an HTTP 2xx status code within 5000 milliseconds.
Retry Schedule: Failed deliveries (non-2xx responses or network timeouts) are retried up to 8 times with exponential backoff over a 72-hour window.
Deduplication: Always inspect id in the event payload to discard duplicate notifications.