Für Entwickler

Wo du NFC.cool anbinden kannst

Ein Webhook ist einfach ein JSON-POST an eine URL deiner Wahl - alles, was HTTP spricht, geht damit.

Häufige Workflow-Muster

• Inventur + Audit-Trail. Tippe einen Tag auf einem Artikel an, NFC.cool POSTet in eine Tabelle oder ein Warehouse-System; eine Zeile erscheint mit Zeitstempel + Tag-Identifier + Payload.

• Lead-Erfassung auf Events. Tippe einen Tag auf deinem Messebanner an, dein CRM sendet automatisch eine Follow-up-E-Mail.

• Smart-Home-Trigger. Tippe einen Tag an der Haustür an, um “Ich bin zu Hause” zu markieren - Home Assistant / Homey / Hubitat empfängt es per Webhook.

• Asset-Tracking. Wartungspersonal tippt Tags auf Geräten an, um Inspektionen zu protokollieren; das Backend baut das Compliance-Log.

• Konferenz-Check-ins. Tippe das NFC-Badge eines Gastes an; der Webhook aktualisiert deine Event-Plattform in Echtzeit.

Webhooks

Aktivierbar unter Einstellungen → Webhook in der App: eine HTTPS-URL eintragen, optional Benutzername/Passwort für HTTP Basic Auth hinterlegen, dann “NFC-Scans” und “QR- & Barcode-Scans” unabhängig voneinander einschalten. Verfügbar auf iOS und Android.

Die App sendet einen einzelnen POST pro Scan an die hinterlegte URL. Es gibt keine separate Retry-Queue: ist dein Endpunkt nicht erreichbar oder liefert er einen Non-2xx-Status zurück, scheitert der POST. Antworte idealerweise mit 204 No Content; jeder 2xx-Status gilt als angenommen.

Webhook-Payload

Content-Type application/json, Body ist pretty-printed JSON:

{
  "identifier" : "04:A2:7F:1B:5E:80:00",
  "date" : "2026-05-12T14:23:01Z",
  "content" : "https://example.com/check-in/abc123"
}

Strukturierte Tags (aktuell OpenPrintTag) fügen zwei weitere Felder hinzu:

{
  "identifier" : "04:A2:7F:1B:5E:80:00",
  "date" : "2026-05-12T14:23:01Z",
  "content" : "Filament Spool #1234",
  "tagType" : "openPrintTag",
  "structured" : { "...geparste Felder..." }
}

Feld-Referenz:

• identifier - Bei NFC-Scans die Hardware-UID des Tags als doppelpunktgetrennter Hex-String in Großbuchstaben (z. B. 04:A2:7F:1B:5E:80:00). Pro Tag stabil, also gut für Deduplizierung. Bei QR- & Barcode-Scans dagegen ein frisch generiertes UUID pro Scan - keine stabile Code-Kennung. In älteren iOS-NFC-Kompatibilitätsmodi, in denen die UID nicht ausgelesen werden kann, steht hier der String NoIdentifierInCompatibilityMode.

• date - ISO 8601, Zeitpunkt des Scans auf dem Gerät.

• content - Dekodierter Inhalt. Bei NFC der NDEF-Record-Wert (URI oder Text), bei QR/Barcode der rohe dekodierte String.

• tagType - Bei einfachen Scans ausgelassen. Bei OpenPrintTag-Scans "openPrintTag".

• structured - Bei einfachen Scans ausgelassen. Geparste strukturierte Payload, wenn tagType gesetzt ist.

Authentifizierung

Webhooks unterstützen ausschließlich HTTP Basic Auth. Unter Einstellungen → Webhook kannst du optional Benutzername und Passwort im iOS-Keychain hinterlegen. Die App antwortet damit auf standardmäßige HTTP 401 / WWW-Authenticate: Basic-Challenges deines Servers.

Heißt: dein Endpunkt entscheidet, ob Auth erforderlich ist. Brauchst du keine, lass die Felder in der App leer und überspring die Challenge serverseitig. Brauchst du sie, antworte auf den ersten POST mit 401 und WWW-Authenticate: Basic realm="…" - das Gerät wiederholt den Request dann mit Authorization: Basic … und den gespeicherten Credentials. Alles läuft über TLS; NFC.cools Server sehen deine Zugangsdaten nie.

Bearer-Token, API-Keys oder HMAC-Signaturen werden aktuell nicht unterstützt. Wenn du sie brauchst, terminiere sie an einem Reverse Proxy (Cloudflare Worker, nginx, …), der Basic in dein Schema übersetzt.

Beispiel-Empfänger

cURL - schneller Smoke-Test

curl -X POST https://dein-server.example/webhook \
  -u 'nfc-cool:dein-passwort' \
  -H 'Content-Type: application/json' \
  -d '{"identifier":"04:A2:7F:1B:5E:80:00","date":"2026-05-12T14:00:00Z","content":"hello"}'

Node.js - Express-Receiver

import express from "express";
import basicAuth from "express-basic-auth";

const app = express();
app.use(express.json());

app.post(
  "/webhook",
  basicAuth({
    users: { "nfc-cool": process.env.WEBHOOK_PASSWORD },
    challenge: true, // damit NFC.cool den POST mit Credentials wiederholt
  }),
  (req, res) => {
    const { identifier, date, content, tagType } = req.body;
    console.log(`scan ${tagType ?? "plain"} ${content} id=${identifier} at ${date}`);
    res.status(204).end();
  }
);

app.listen(3000);

Python - FastAPI-Receiver

import os
import secrets
from fastapi import FastAPI, Depends, HTTPException, Request, status
from fastapi.security import HTTPBasic, HTTPBasicCredentials

app = FastAPI()
security = HTTPBasic()

def check(creds: HTTPBasicCredentials = Depends(security)):
    ok_user = secrets.compare_digest(creds.username, "nfc-cool")
    ok_pass = secrets.compare_digest(creds.password, os.environ["WEBHOOK_PASSWORD"])
    if not (ok_user and ok_pass):
        raise HTTPException(
            status.HTTP_401_UNAUTHORIZED,
            headers={"WWW-Authenticate": 'Basic realm="nfc-cool"'},
        )

@app.post("/webhook")
async def webhook(request: Request, _: None = Depends(check)):
    body = await request.json()
    print(f"scan: {body['content']} id={body['identifier']}")
    return {"status": "ok"}

App Intents & Kurzbefehle

NFC.cool Tools auf iOS stellt eine Handvoll App Intents bereit, die du in die Kurzbefehle-App, Automationen, Fokus-Modi oder Apple Intelligence einbauen kannst.

Die iOS-18-Varianten (NFC Scan, QR Scan, Document Scan, Object Scan, Room Scan) erscheinen direkt in Spotlight und im Action-Button-Picker.

URL-Schemata

Für Deep-Links aus anderen iOS-Apps, Widgets oder Home-Screen-Shortcuts registriert NFC.cool Tools diese URLs:

nfcforiphone://scan-nfc
nfcforiphone://scan-code
nfcforiphone://scan-document
nfcforiphone://scan-object       (iOS 17+)
nfcforiphone://scan-room         (iOS 17+)

Jede dieser URLs öffnet direkt den passenden Scanner. Die Schemata nfc:// und geo:// sind ebenfalls registriert, um externe Tag- bzw. Koordinaten-Links zu übernehmen.

Maschinenlesbare Ressourcen

Auffindbare Feeds für Tooling, Suchmaschinen und KI-Agenten:

Du baust auf NFC.cool auf, oder kennst einen Integrations-Partner, der hier stehen sollte? Schreib uns: hello@nfc.cool.