Webhooks API

LinkMe supports per-app webhook subscriptions in the Developer section of the portal.

Webhooks are the recommended way to move LinkMe events into analytics pipelines, warehouse jobs, and operational automations without polling REST endpoints. Most teams subscribe to click and app-open events first, then add claim and deferred-claim flows once attribution QA is in place.

Supported event types

link.click
link.token_created
link.claim
link.app_open
link.deferred_claim_attempt

Delivery envelope

{
  "id": "uuid",
  "event": "link.click",
  "ts": "2026-02-11T12:34:56.789Z",
  "app_id": "app_123",
  "data": {
    "link_id": "abc123"
  }
}

Reliability model

retriable errors are retried with backoff
retries stop after a max attempt count
every attempt is recorded in delivery history
repeated failures can auto-disable the webhook

In practice, you should treat webhook receivers as at-least-once delivery consumers. Build idempotency on the id field and avoid assuming strict attempt ordering across retries.

Optional signing

If signing is enabled, LinkMe auto-generates a signing secret and requests include:

X-LinkMe-Signature: sha256=<hmac>

Signature is HMAC-SHA256 over the raw request body.

For Node backends, @li-nk.me/node-sdk exposes verifyLinkMeWebhookSignature(...) and webhook envelope parsing helpers so you can reuse core receiver logic across projects.

Receiver implementation guidance

Use this baseline approach in production:

Read the raw request body before JSON parsing.
Verify X-LinkMe-Signature against the raw payload.
Return 2xx quickly after validation.
Process downstream work asynchronously (queue or worker).
Deduplicate by event id in your sink to handle retries safely.

This pattern keeps delivery healthy and prevents endpoint latency from causing avoidable retries.

Typical payload handling workflow

Parse the envelope (id, event, ts, app_id, data).
Route by event type to dedicated handlers.
Enrich with campaign metadata or app/user context.
Forward to your destination system (BI, CDP, alerting, CRM).
Store processing state for replay and audit support.

Portal management

Use Portal -> App -> Developer -> Webhooks to:

create webhook endpoints
pick event subscriptions
set/remove signing secret
enable/disable endpoints
inspect delivery history

For new integrations, begin with one endpoint and a narrow event set, validate delivery history for 24 hours, then expand subscriptions gradually. This keeps rollout risk low while still giving quick operational feedback.

Appearance