Webhooks allow you to build integrations that subscribe to events on Jmpy.me. When one of these events is triggered, Jmpy.me sends an HTTP POST payload in JSON format to the webhook’s configured target URL. Webhooks are useful for:
  • Updating databases when links are clicked or QR codes are scanned.
  • Triggering marketing automation sequences.
  • Sending notifications in Discord, Slack, or internal dashboards in real time.

​
Supported Events

Jmpy.me currently supports the following events:
Event NameDescription
link.clickedTriggered every time a user clicks one of your short URLs.
link.clicked.uniqueTriggered on the first click from a unique user on a short URL.
link.clicked.utmTriggered when a short URL with UTM parameters is clicked.
qr.scannedTriggered every time someone scans one of your QR codes.
qr.scanned.uniqueTriggered on the first scan from a unique user on a QR code.
link.createdTriggered when a new short URL is created.
qr.createdTriggered when a new QR code is generated.

​
Webhook Filtering Options

When subscribing to webhook events, you can specify optional filter parameters to only receive dispatches when specific conditions are met. These filters are evaluated server-side before dispatching, and do not alter the shape of the payload itself.

​
Filter Fields

  • short_code: Comma-separated list of short codes (e.g., qXAguG). Limits dispatches to matching links. Supported on: link.clicked, link.clicked.unique, link.clicked.utm.
  • qr_code_id: Comma-separated list of QR code UUIDs. Limits dispatches to matching QR codes. Supported on: qr.scanned, qr.scanned.unique.
  • campaign_id: Filter by campaign ID (UUID). Limits dispatches to links/QR codes belonging to a specific campaign.
  • is_expiring: Boolean. Filter based on whether the link/QR code has an expiration date set (true or false).
  • is_password_protected: Boolean. Filter based on whether password protection is enabled on the resource (true or false).
  • has_utm_params: Boolean. Filter based on whether the link click has UTM tracking parameters (true or false).
  • is_unique: Boolean. Filter for unique click/scan events (true or false).
  • custom_alias: Boolean. Filter based on whether the link uses a custom alias instead of a randomly generated one (true or false).
  • tags: List of tags. Trigger only if the link/QR code contains all the specified tags.
  • branded_domain: Comma-separated list of custom branded domains.
  • subdomain: Comma-separated list of subdomains.
  • url_type: Trigger based on the branding type (standard, branded, subdomain).

​
Payload Formats

Every webhook event request sent to your receiver URL has a consistent outer envelope: 
{
  "event": "event.type",
  "subscription_id": "uuid",
  "timestamp": "2026-07-05T20:55:00.000Z",
  "data": {
    // Event-specific data payload
  }
}
This payload is dispatched when a short URL click event occurs (also used by link.clicked.unique and link.clicked.utm). 
{
  "event": "link.clicked",
  "subscription_id": "8b51d8b7-83ab-41c3-bb5a-a38f420a32ef",
  "timestamp": "2026-07-05T20:55:00.000Z",
  "data": {
    "id": "click-uuid-123456",
    "interaction_id": "click-uuid-123456",
    "interaction_click": "Click",
    "interaction_scan": null,
    "interaction_type": "Click",
    "click_id": "click-uuid-123456",
    "scan_id": null,
    "click_detail": "click",
    "short_id": "link-uuid-abcde",
    "link_id": "link-uuid-abcde",
    "short_code": "my-alias",
    "short_url": "https://jmpy.me/my-alias",
    "original_url": "https://example.com/dest-url",
    "language": "en-US",
    "is_unique": true,
    "session_id": "session-123456",
    // "is_new_location": false,
    // "is_new_referrer": false,
    // "is_new_device": false,
    "geo": {
      "country": "United States",
      "country_code": "US",
      "region": "California",
      "city": "Mountain View",
      "timezone": "America/Los_Angeles"
    },
    "device": {
      "device_type": "desktop",
      "device_brand": "Apple",
      "device_model": "Macintosh",
      "browser": "Chrome",
      "browser_version": "120.0.0",
      "os": "macOS",
      "os_version": "14.1.2",
      "os_platform": "Intel"
    },
    "traffic": {
      "traffic_source": "twitter",
      "traffic_medium": "social",
      "organic_vs_paid": "organic",
      "referer": "https://twitter.com/",
      "referrer_domain": "twitter.com"
    },
    "utm": {
      "utm_source": "social",
      "utm_medium": "cpc",
      "utm_campaign": "black_friday_2026",
      "utm_term": "sale",
      "utm_content": "banner_ad"
    },
    "ab_test": {
      "ab_test_id": "c16d56df-7170-4f5c-897d-cc162b2bc820",
      "variant_id": "a901ff2a-b605-4f4d-8ce8-971c67d98341",
      "variant_name": "Variant A"
    },
    "clicked_at": "2026-07-05T20:54:59.000Z",
    "campaign_id": "campaign-uuid-999",
    "campaign_name": "BFCM 2026 Campaign",
    "url_type": "standard",
    "link_branding": "standard",
    "branded_domain": null,
    "subdomain": null,
    "is_dynamic": false,
    "is_password_protected": false,
    "expires_at": null,
    "custom_alias": null,
    "tags": [],
    "has_utm_params": true,
    "is_qr_scan": false
  }
}

​
2. qr.scanned Payload Example

This payload is dispatched when a QR code scan event occurs (also used by qr.scanned.unique). 
{
  "event": "qr.scanned",
  "subscription_id": "d04a6015-18ee-449e-ba89-91306ef456fa",
  "timestamp": "2026-07-05T20:55:00.000Z",
  "data": {
    "scan_id": "scan-uuid-123456",
    "qr_code_id": "qr-uuid-78910",
    "qr_code_name": "My Business Card QR",
    "content_type": "url",
    "qr_content": "https://jmpy.me/my-alias",
    "interaction_click": null,
    "interaction_scan": "Scan",
    "interaction_type": "Scan",
    "language": "en-US",
    "is_unique": true,
    "session_id": "session-123456",
    // "is_new_location": false,
    // "is_new_referrer": false,
    // "is_new_device": false,
    "geo": {
      "country": "United States",
      "country_code": "US",
      "region": "California",
      "city": "Mountain View",
      "timezone": "America/Los_Angeles"
    },
    "device": {
      "device_type": "mobile",
      "device_brand": "Apple",
      "device_model": "iPhone",
      "browser": "Safari",
      "browser_version": "16.5",
      "os": "iOS",
      "os_version": "16.5",
      "os_platform": "iPhone"
    },
    "utm": {
      "utm_source": "social",
      "utm_medium": "cpc",
      "utm_campaign": "black_friday_2026",
      "utm_term": "sale",
      "utm_content": "banner_ad"
    },
    "ab_test": {
      "ab_test_id": null,
      "variant_id": null,
      "variant_name": null
    },
    "scanned_at": "2026-07-05T20:54:59.000Z",
    "campaign_id": "campaign-uuid-999",
    "campaign_name": "BFCM 2026 Campaign",
    "url_type": "standard",
    "link_branding": "standard",
    "branded_domain": null,
    "subdomain": null,
    "is_dynamic": false,
    "is_password_protected": false,
    "expires_at": null,
    "custom_alias": null,
    "tags": []
  }
}
This payload is dispatched when a new short URL is created. 
{
  "event": "link.created",
  "subscription_id": "a901ff2a-b605-4f4d-8ce8-971c67d98341",
  "timestamp": "2026-07-05T20:55:00.000Z",
  "data": {
    "id": "e0e854fa-87a3-48ee-89a3-9372bd74b124",
    "name": "My New Campaign Link",
    "campaign_id": null,
    "campaign_name": null,
    "short_code": "new-alias",
    "short_url": "https://jmpy.me/new-alias",
    "destination_url": "https://example.com/target-url",
    "is_password_protected": false,
    "expires_at": null,
    "is_dynamic": false,
    "tracking_enabled": true,
    "created_at": "2026-07-05T20:55:00.000Z",
    "source": "DASHBOARD",
    "qr_code_url": "https://jmpy.me/storage/qrs/e0e854fa.png",
    "qr_code_html": "<img src=\"https://jmpy.me/storage/qrs/e0e854fa.png\" alt=\"QR Code\" />",
    "qr_code_excel_sheet_formula": "=IMAGE(\"https://jmpy.me/storage/qrs/e0e854fa.png\")",
    "qr_code_excel_sheet_formula_IMAGE": "https://jmpy.me/storage/qrs/e0e854fa.png",
    "short_code_id": "e0e854fa-87a3-48ee-89a3-9372bd74b124",
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_term": null,
    "utm_content": null,
    "branded": "no",
    "subdomain": null,
    "branded_domain": null,
    "custom_alias": null,
    "tags": [],
    "has_utm_params": false
  }
}

​
4. qr.created Payload Example

This payload is dispatched when a new QR code is generated. 
{
  "event": "qr.created",
  "subscription_id": "c2049ba3-8b77-4950-a92c-8efcf9bc5133",
  "timestamp": "2026-07-05T20:55:00.000Z",
  "data": {
    "id": "315fb6c8-04ff-42bb-ae4b-74cdcfbeba21",
    "name": "My Restaurant Menu QR",
    "content_type": "url",
    "content_url": "https://jmpy.me/new-alias",
    "qr_code_url": "https://jmpy.me/storage/qrs/315fb6c8.png",
    "qr_code_html": "<img src=\"https://jmpy.me/storage/qrs/315fb6c8.png\" alt=\"QR Code\" width=\"200\" height=\"200\" />",
    "qr_code_excel_sheet_formula": "=IMAGE(\"https://jmpy.me/storage/qrs/315fb6c8.png\")",
    "is_password_protected": false,
    "expires_at": null,
    "is_dynamic": false,
    "tracking_enabled": true,
    "created_at": "2026-07-05T20:55:00.000Z",
    "qr_code_excel_sheet_formula_IMAGE": "https://jmpy.me/storage/qrs/315fb6c8.png",
    "qr_code_id": "315fb6c8-04ff-42bb-ae4b-74cdcfbeba21",
    "branded": "no",
    "campaign_id": null,
    "campaign_name": null,
    "qr_code_link_branding": "standard",
    "branded_domain": null,
    "subdomain": null,
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_term": null,
    "utm_content": null,
    "has_utm_params": false
  }
}