Skip to content
TapLogic API
Italiano

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.scannedSomeone scanned a tag. data.object is the same Scan object as GET /scans.
tag.assignedA tag moved to another member (or to none).
member.invitedAn invitation went out: the seat is held until the invitation expires.
member.joinedThe 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=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);
});

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

AttemptWait before the attempt
21 min
34 min
416 min
51 h 4 min
64 h 16 min
78 h
88 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"