Webhooks
TapLogic sends a signed POST request to your server for each event you choose. Your system learns at once about a scan, an assigned tag or a new person on the team.
Events
tag.scanned | Someone scanned a tag. data.object is the same Scan object as GET /scans. |
tag.assigned | A tag moved to another member (or to none). |
member.invited | An invitation went out: the seat is held until the invitation expires. |
member.joined | The invited person accepted and joined the company. |
{
"id": "evt_9f3Kd2LmQx81ZpRt0aBcYvWs",
"object": "event",
"type": "tag.scanned",
"api_version": "2026-11-18",
"created": 1763457600,
"livemode": true,
"data": {
"object": {
"id": "cm3scn0001",
"object": "scan",
"tag_id": "cm3tag0001",
"code": "K7P2QX9M",
"occurred_at": "2026-11-18T09:20:00.000Z",
"outcome": "ok",
"action_type": "instagram",
"destination": "https://www.instagram.com/esempio",
"location_source": "installation",
"member_id": null,
"product_id": "cm3prd0001",
"country": "IT",
"city": "Milano",
"livemode": true
}
}
}Registering an endpoint
Create the endpoint in the app (Settings → API and webhooks → Webhooks) or through the API. The response holds the whsec_… secret only once. Endpoints created with a test key receive only demo tag events.
curl -X POST "https://api.taplogic.it/v1/webhooks" \
-H "Authorization: Bearer $TAPLOGIC_API_KEY" \
-H "Idempotency-Key: endpoint-gestionale" \
-H "Content-Type: application/json" \
-d '{"url":"https://esempio.it/webhook/taplogic","enabled_events":["tag.scanned","member.joined"],"description":"Gestionale"}'Verifying the signature
Every request carries the TapLogic-Signature header with a timestamp t and one or more v1 signatures. The signature is the hex HMAC-SHA256, keyed with the endpoint secret, of the string {t}.{raw body}. Compute it on the exact body received, before any JSON parsing, and reject timestamps older than 5 minutes.
POST /webhook/taplogic HTTP/1.1
Content-Type: application/json
User-Agent: TapLogic-Webhooks/1.0
TapLogic-Event-Id: evt_9f3Kd2LmQx81ZpRt0aBcYvWs
TapLogic-Signature: t=1763457600,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bdimport { createHmac, timingSafeEqual } from "node:crypto";
const TOLLERANZA_SECONDI = 300;
export function verificaFirma(corpoGrezzo, intestazione, segreto) {
let timestamp = 0;
const firme = [];
for (const parte of intestazione.split(",")) {
const [chiave, valore = ""] = parte.trim().split("=");
if (chiave === "t") timestamp = Number(valore);
if (chiave === "v1") firme.push(valore);
}
if (!timestamp || firme.length === 0) return false;
if (Math.abs(Date.now() / 1000 - timestamp) > TOLLERANZA_SECONDI) return false;
const attesa = createHmac("sha256", segreto)
.update(`${timestamp}.${corpoGrezzo}`)
.digest("hex");
return firme.some(
(firma) =>
firma.length === attesa.length &&
timingSafeEqual(Buffer.from(firma), Buffer.from(attesa)),
);
}
app.post("/webhook/taplogic", express.raw({ type: "application/json" }), (req, res) => {
const corpo = req.body.toString("utf8");
if (!verificaFirma(corpo, req.get("TapLogic-Signature") ?? "", process.env.TAPLOGIC_WEBHOOK_SECRET)) {
return res.status(400).send("firma non valida");
}
const evento = JSON.parse(corpo);
res.sendStatus(200);
});After a secret rotation (POST /webhooks/{id}/rotate-secret) the previous secret stays valid for 24 hours: meanwhile each event carries two v1 signatures, one per secret.
Responding and retries
- Reply with a 2xx status within 10 seconds. Do heavy work later, in a queue.
- A redirect, an error, a 3xx/4xx/5xx or a timeout counts as a failed delivery.
- Failed deliveries are retried with growing waits, for 21 h 41 min in total: 8 attempts.
- An event can arrive more than once and out of order. Use id to drop duplicates and created to order them.
- After 25 failed deliveries in a row the endpoint is disabled. Enable it again in the app or with status=enabled.
Waits between attempts
| Attempt | Wait before the attempt |
|---|---|
| 2 | 1 min |
| 3 | 4 min |
| 4 | 16 min |
| 5 | 1 h 4 min |
| 6 | 4 h 16 min |
| 7 | 8 h |
| 8 | 8 h |
Test event
POST /webhooks/{id}/test sends a signed webhook.test event now and returns the result. Every attempt, tests included, appears in the app's delivery log and in GET /webhooks/{id}/deliveries.
curl -X POST "https://api.taplogic.it/v1/webhooks/cm3whk0001/test" \
-H "Authorization: Bearer $TAPLOGIC_API_KEY"