miji.beSending short URL click events to external systems via webhooks lets you push lead data to your CRM, instant alerts to Slack, and aggregations into Google Sheets without manual exports. At hundreds of thousands of clicks per day, CSV export plus manual import collapses, so webhook-based real-time integration becomes practically required. Bitly, Rebrandly, and Short.io all expose webhooks, and the pattern is now standard in SaaS.
Start by defining the payload schema. Click events should include short code, original URL, click time in UTC, IP, User-Agent, Referer, geo (country, region), device type, and UTM parameters. Use JSON Schema for strict validation, and place additions under an "extensions" object rather than at the root for forward compatibility. Stripe and GitHub webhook payloads are good references.
Signature verification is non-negotiable. The sender HMACs the payload with a shared secret, and the receiver verifies before processing. GitHub's "X-Hub-Signature-256" and Stripe's "Stripe-Signature" headers exemplify the pattern. IP allowlists alone leave room for arbitrary payload injection. Pair signatures with timestamp checks (accept only requests within 5 minutes) to also block replays.
Idempotency is the most overlooked detail. Network errors trigger sender retries, and naive receivers duplicate-process. Assign a unique "event_id" per event and skip any ID seen in the past 24 hours, using Redis or DynamoDB TTL for automatic cleanup. Retry logic should use exponential backoff (1m, 5m, 30m, 2h, 8h) up to five attempts on 5xx and timeouts, while 4xx halts retries immediately and alerts. Receiver endpoints should ack within a second and offload heavy work to async queues like SQS or Pub/Sub.