Webhooks
Configure real-time event triggers for click tracking, domain verification, and campaign analytics.
Generate API Key View DocumentationWebhook Setup
Connect your endpoints to HyperSnap’s event bus in three steps. Navigate to Integrations > Webhooks in your dashboard, paste your HTTPS endpoint URL, and select your trigger scope. All endpoints must support TLS 1.2+ and respond with a 2xx status code within 3 seconds to acknowledge receipt.
Once registered, HyperSnap validates your endpoint with a handshake containing a `challenge_token`. Echo this token back in the response body to activate the subscription. You can manage up to 15 active webhook destinations per organization, with rate limiting capped at 1,200 events per minute per endpoint.
Event Types
HyperSnap emits structured events for every user interaction and system milestone. Choose which signals route to your pipeline.
link.click.registered
Triggers immediately when a visitor resolves a short URL. Includes referrer data, device fingerprint, and geographic coordinates.
link.click.converted
Fires when a click matches a predefined UTM pattern or passes through a pixel-tagged landing page. Used for ROI attribution.
domain.verification.complete
Signals that a custom domain has passed DNS TXT record validation and SSL provisioning. Useful for automated provisioning workflows.
campaign.threshold.met
Dispatched when a link group exceeds a configured click quota (e.g., 10,000 impressions). Supports dynamic alert routing.
Payload Structure & Retry Policies
All webhook deliveries use `application/json` with HMAC-SHA256 signature validation. Verify the `x-hypersnap-signature` header against your secret key to prevent spoofed requests.
Standard payload envelope:
{"event": "link.click.registered", "timestamp": "2024-06-15T08:32:11Z", "data": {"short_url": "https://hs.app/cx92m", "destination": "https://acme-corp.io/summer-sale", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)", "ip_hash": "a1b2c3d4e5f6", "geo": {"country": "US", "city": "Denver"}, "referrer": "https://twitter.com/"}}
If your endpoint returns a 4xx/5xx status or times out, HyperSnap applies an exponential backoff retry schedule: 30s, 2m, 10m, 1h, 6h. After five failed attempts, the subscription pauses and notifies your designated admin email. You can resume delivery manually or via the `/v2/webhooks/resume` API endpoint. Dead-letter queues retain failed payloads for 30 days for debugging.