Link automation and webhooks for clicks

The v1 event catalog includes six event types:

• link.created — a new short link was created
• link.updated — a non-takedown mutation such as a destination change, slug change, or expiration change
• link.takedown_updated — a moderation or safety workflow changed link availability
• domain.verification_updated — a domain verification or readiness state changed
• link.clicked — a short link was clicked, excluding bot traffic
• link.qr_scanned — a QR code was scanned, excluding bot traffic

Endpoints are workspace-scoped and subscription filtering is by event type. Per-link or per-domain filtering is not part of the v1 webhook subscription model.

Every webhook delivery uses a consistent envelope with a stable id, type, api_version, created_at, organization_id, workspace_id, and a data object. The data object for click and scan events includes stable ids (link_id, domain_id), short_url, domain_name, short_code, touch_type, country, device_category, browser_family, os_family, referrer_host, social_source, and UTM parameters where present.

Raw long URLs are intentionally excluded to avoid leaking query-sensitive or signed destination parameters. API keys, signing secrets, and other credentials are never included in any webhook payload. Destination context is exposed as the safe fields destination_host and destination_url_capped on lifecycle events.

Delivery is asynchronous. Events are enqueued after the redirect completes so the redirect path is never blocked. Nimriz does not guarantee global delivery order or per-resource ordering across event types. Two events for the same link may arrive in any sequence.

Build your receiver to be order-tolerant. Use the created_at timestamp in the envelope to reason about chronological order, and use the before and after field snapshots on link.updated events to determine correct state transitions rather than tracking state on your side.

Nimriz delivers each event at-least-once and retries up to six times total per endpoint. The retry schedule uses exponential backoff: the first retry fires after 60 seconds, then 120, 240, 480, and finally 900 seconds. Retryable outcomes include network failures, missing responses, and HTTP 408, 409, 425, 429, and 5xx responses. Any other non-2xx response causes an immediate terminal failure for that attempt.

After all six attempts are exhausted, the delivery moves to dead-letter state. It will not retry further unless you manually replay it from the endpoint's delivery history view. Replay re-delivers the original event envelope with the same id and payload, a fresh timestamp and signature, and the header X-Nim-Delivery-Reason: replay.

Delivery is at-least-once, so your processing must be idempotent. Before executing any side effect, check whether you have already processed an event with the same id value from the envelope. The id is stable across all delivery attempts for the same business event and is preserved on manual replay. Do not dedupe on attempt number or delivery timestamp, as those change on every attempt.

Every delivery is signed with HMAC-SHA256. Compute the expected signature by running HMAC-SHA256(signingSecret, "{X-Nim-Timestamp}.{rawRequestBody}") and compare it in constant time against the X-Nim-Signature: v1=<hex> header. Always read the raw request body bytes before parsing JSON, as re-serialization can change byte content and break verification.

You may also enforce a freshness window against X-Nim-Timestamp to reject replayed requests, but remember that legitimate retries and manual replays also use new timestamps on existing event ids. See the webhook docs for a complete Node.js example.

No custom code is required for the most common recipes. Zapier, Make, and n8n connect to Nimriz using scoped installation tokens available from your integrations settings. Once connected, you can build workflows entirely inside those platforms: trigger on a Nimriz event, then add actions such as posting a Slack message, appending a Google Sheet row, or updating a CRM record. For cases where no matching action exists in those platforms, a Generic HTTP destination can POST events to any HTTPS endpoint with custom headers and payload templates.

Generic HTTP destinations are available on Growth and above. Click-event webhooks (link.clicked and link.qr_scanned) are available on Professional and above. Basic lifecycle webhook subscriptions and no-code integration connections are also on supported plans. Check the integrations and destinations feature page or the pricing page for current plan details.