Webhook
TapLogic invia una richiesta POST firmata al tuo server per ogni evento che scegli. Così il tuo gestionale sa subito di un tocco, di un tag assegnato o di una nuova persona nel team.
Eventi
tag.scanned | Qualcuno ha toccato un tag. data.object è lo stesso oggetto Scan di GET /scans. |
tag.assigned | Un tag è passato a un altro membro (o a nessuno). |
member.invited | È partito un invito: il posto è impegnato finché l'invito non scade. |
member.joined | La persona invitata ha accettato ed è entrata nell'azienda. |
{
"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
}
}
}Registrare un endpoint
Crea l'endpoint dall'app (Impostazioni → API e webhook → Webhook) o via API. La risposta contiene il segreto whsec_… una sola volta. Gli endpoint creati con una chiave di test ricevono solo gli eventi dei tag demo.
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"}'Verificare la firma
Ogni richiesta porta l'intestazione TapLogic-Signature con un timestamp t e una o più firme v1. La firma è l'HMAC-SHA256 esadecimale, calcolato con il segreto dell'endpoint, della stringa {t}.{corpo grezzo}. Calcola la firma sul corpo esatto ricevuto, prima di qualsiasi parsing JSON, e rifiuta i timestamp più vecchi di 5 minuti.
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);
});Dopo una rotazione del segreto (POST /webhooks/{id}/rotate-secret) il segreto precedente resta valido 24 ore: in quel periodo ogni evento porta due firme v1, una per segreto.
Rispondere e ritentativi
- Rispondi con un codice 2xx entro 10 secondi. Fai il lavoro pesante dopo, in coda.
- Un redirect, un errore, un 3xx/4xx/5xx o un timeout contano come consegna fallita.
- Le consegne fallite si ritentano con attese crescenti, per 21 h 41 min in tutto: 8 tentativi.
- Un evento può arrivare più di una volta e non sempre in ordine. Usa id per scartare i doppioni e created per ordinare.
- Dopo 25 consegne fallite di seguito l'endpoint viene disattivato. Lo riattivi dall'app o con status=enabled.
Attese tra i tentativi
| Tentativo | Attesa prima del tentativo |
|---|---|
| 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 |
Evento di prova
POST /webhooks/{id}/test invia subito un evento webhook.test firmato e restituisce l'esito. Ogni tentativo, anche di prova, compare nel registro consegne dell'app e in GET /webhooks/{id}/deliveries.
curl -X POST "https://api.taplogic.it/v1/webhooks/cm3whk0001/test" \
-H "Authorization: Bearer $TAPLOGIC_API_KEY"