Vai al contenuto
TapLogic API
English

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.scannedQualcuno ha toccato un tag. data.object è lo stesso oggetto Scan di GET /scans.
tag.assignedUn tag è passato a un altro membro (o a nessuno).
member.invitedÈ partito un invito: il posto è impegnato finché l'invito non scade.
member.joinedLa 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=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
import { 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

TentativoAttesa prima del tentativo
21 min
34 min
416 min
51 h 4 min
64 h 16 min
78 h
88 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"