Automating links: when to use the API and when to use webhooks

There are two directions an integration can run. Either your code calls Lnki, or Lnki calls your code. The API is the first; webhooks are the second. Choosing the right one for each job keeps an integration small.

The API: your system gives the orders

The API manages links, QR codes and bulk imports. You can create a link, list and search your links, read one, update it and archive it; make and restyle QR codes; and create up to 500 links in one import request. It is available on the Business plan, where each key may make up to 5,000 requests a minute. Link creation has its own ceiling of 60 new links a minute per workspace.

Requests are authenticated with a short-lived access token. You create an API key on the API Keys page (it starts with lnki_live_ and is shown once), exchange it for an access token that lasts an hour, and send that token as a bearer token. A refresh token that comes with it gets you the next one without sending the key again.

curl -X POST https://lnki.io/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "api_key",
    "api_key": "YOUR_API_KEY"
  }'

curl -X POST https://lnki.io/api/v1/links \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_url": "https://example.com/orders/1042",
    "title": "Order 1042 tracking"
  }'

Reach for the API when links are a by-product of something else: an order confirmation that needs a tracking link, a CMS that should mint a short link for every new article, a nightly job that keeps destinations in step with a product catalogue. The API reference lists every field, and make your first API request gets you to a working call.

Webhooks: Lnki reports back

A webhook is a URL on your server that Lnki sends an HTTP POST to when something happens. You choose which events each webhook receives:

• link.created, link.updated and link.deleted
• link.clicked
• domain.connected
• bio.clicked
• api_key.created

Use webhooks when you would otherwise be polling. Rather than asking every minute whether a link has been clicked, let the click arrive: post it to a chat channel, add it to a CRM record, or trigger the next step of a workflow.

Verify every delivery

Each webhook has a signing secret that starts with whsec_. Every delivery carries an X-Lnki-Signature header: sha256= followed by the HMAC-SHA256 of the raw request body, keyed with that secret. Compute the same value on your side and reject the request if they differ. Without that check, anyone who discovers the URL can send you fake events.

Expect retries and batches

• A delivery that times out, or is answered with a 429 or a 5xx status, is retried with increasing delays, up to five attempts in total. Answer with a 2xx status as soon as you have stored the event, and do the slow work afterwards.
• The X-Lnki-Delivery-Key header stays the same across retries of one delivery. Use it to ignore a delivery you have already processed.
• Clicks on a busy link are grouped. Instead of one request per click you receive a link.clicked.batch event carrying up to 50 clicks.
• After five failed deliveries in a row a webhook is marked as failed and stops receiving events until you resume it.

Putting them together

A typical integration uses both. Your shop calls the API to create a link for each order. A webhook subscribed to link.clicked tells the shop when the customer opened it. Neither side polls the other, and each half can be tested on its own.

Webhooks are available on paid plans: up to five on Starter, ten on Pro and no cap on Business. Receive events with webhooks covers creating one and reading the delivery log.