API Docs
v1.0
Webhooks
Receive an HTTP POST at your own URL when events happen in your TrimLink account.
Setup
- Add endpoints in Dashboard, Settings, API & Integrations. Endpoints are managed in the dashboard only, not with an API key.
- Webhooks need Growth (3 endpoints), Teams (10) or Enterprise (unlimited).
- The endpoint URL must use HTTPS. Pick at least one event per endpoint.
- The signing secret is shown once, when you create the endpoint. Store it then.
- Use the test button to send a sample
link.createdevent with"test": truein its data.
Events
| Event | When | data fields |
|---|---|---|
link.created | A link was created. | linkId, shortCode, originalUrl, shortUrl, createdAt |
link.clicked | A link received a tracked click or QR scan. | linkId, shortCode, deviceType, countryCode, referrer, clickSource, clickedAt |
link.updated | The title, description or expiry of a link changed. | linkId, shortCode, changes { title, description, expiresAt }, updatedAt |
link.deleted | A link was deleted. | linkId, shortCode, deletedAt |
In link.clicked, referrer is the referring page without its query string, clickSource is direct, qr or api, and deviceType is a coarse bucket such as mobile. No IP address or full user agent is sent.
Payload Format
Every payload has an id, the event name, an ISO timestamp and the event data:
Example: link.clicked
{
"id": "link.clicked_9c8b7a6d-5e4f-4a3b-8291-0d1e2f3a4b5c",
"event": "link.clicked",
"timestamp": "2026-01-31T12:00:00.000Z",
"data": {
"linkId": "9c8b7a6d-5e4f-4a3b-8291-0d1e2f3a4b5c",
"shortCode": "my-link",
"deviceType": "mobile",
"countryCode": "US",
"referrer": "https://news.ycombinator.com/item",
"clickSource": "qr",
"clickedAt": "2026-01-31T12:00:00.000Z"
}
}Request Headers
Webhook Headers
Content-Type: application/json
User-Agent: TrimLink-Webhook/1.0
X-TrimLink-Event: link.clicked
X-TrimLink-Signature: sha256=<hex HMAC-SHA256 of the raw body>Verifying Signatures
The signature is sha256= followed by the hex HMAC-SHA256 of the raw request body, keyed with your signing secret. Compute it over the exact bytes you received. Never skip this check in production, because anyone can POST to your URL.
const crypto = require('crypto');
const express = require('express');
const app = express();
function verifyWebhook(rawBody, signature, secret) {
const expected =
'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const a = Buffer.from(signature || '');
const b = Buffer.from(expected);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// Read the body as raw bytes. Re-serializing parsed JSON can change it.
app.post('/webhooks/trimlink', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.get('X-TrimLink-Signature');
if (!verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}
res.status(200).send('OK'); // answer within 5 seconds
const { event, data } = JSON.parse(req.body.toString('utf8'));
console.log(`Received ${event}`, data);
});Delivery
- TrimLink sends one POST per event to every active endpoint subscribed to it.
- Any 2xx status counts as delivered. Your endpoint has 5 seconds to answer.
- There are no retries. A failed or slow delivery is not sent again, so keep the handler fast and do slow work after you answer.
- Each failure adds one to the failure count shown in the dashboard, and a success resets it. An endpoint is never switched off for failing.
Best Practices
- Verify signatures: Check X-TrimLink-Signature on the raw body before trusting anything.
- Answer fast: Return 200 right away and process the event in the background, within the 5 second limit.
- Expect gaps: Deliveries are not retried. Use the API or dashboard as the source of truth for totals.
- Do not dedupe on id alone: The payload id is the event name plus the link ID, so every click on one link shares it.