Webhooks

Receive real-time HTTP POST notifications when events happen in your workspace. Configure endpoints, choose events, and verify signatures for secure delivery.

Creating a Webhook

POST/v1/webhooks

{
  "url": "https://your-app.com/webhooks/mask",
  "events": ["link.clicked", "page.viewed"],
  "secret": "whsec_your_signing_secret"
}

Verifying Signatures

Every webhook delivery includes a X-Mask-Signature header. Verify it with HMAC-SHA256 using your webhook secret to ensure the payload is authentic.

Node.js example

import crypto from "crypto";

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Event Types

Event	Description
link.created	A new short link was created
link.clicked	A short link was clicked
link.updated	A link's destination or settings changed
link.deleted	A link was deleted
page.published	A bio page was published
page.viewed	A bio page was viewed
qr.scanned	A QR code was scanned
domain.verified	A custom domain DNS verification completed

Payload Example

link.clicked

{
  "id": "evt_abc123",
  "type": "link.clicked",
  "timestamp": "2026-03-13T12:00:00Z",
  "data": {
    "linkId": "clk_xyz789",
    "slug": "my-link",
    "originalUrl": "https://example.com",
    "referrer": "https://twitter.com",
    "country": "US",
    "device": "mobile",
    "browser": "Chrome"
  }
}

Retry Policy

If your endpoint returns a non-2xx status code, MASK retries up to 5 times with exponential backoff (1s, 5s, 30s, 2m, 10m). After all retries fail, the event is marked as failed in your webhook logs. You can replay failed events from the dashboard.