Workflow-Modus

Integrieren Sie Visiono in externe Workflows mit sicheren signierten URLs.

Übersicht

Der Workflow-Modus ermöglicht externen Systemen, die Visiono-Fotosammlung nahtlos in ihre Prozesse einzubetten. Benutzer werden von externen Systemen (wie Zendesk-Tickets oder CRM-Datensätzen) zu Visiono weitergeleitet, schließen Foto-Uploads ab und werden automatisch mit verifizierten Daten zurückgeleitet.

Hauptfunktionen

Funktion	Beschreibung
Signierte URLs	HMAC-SHA256-Signatur verhindert Manipulation
Auto-Weiterleitung	Rückkehr zum externen System nach Abschluss
Versteckte Felder	Vorausgefüllte Daten nicht für Benutzer sichtbar
Pro-Einreichungs-Tracking	Externe Quelle und Referenz gespeichert
Signaturverifizierung	Verifizieren, dass Weiterleitungsdaten nicht geändert wurden

So funktioniert es

sequenceDiagram
    participant E as Externes System
    participant V as Visiono
    participant U as Benutzer

    E->>E: Signierte URL generieren
    E->>U: Link an Benutzer senden
    U->>V: Signierte URL öffnen
    V->>V: Signatur validieren
    V->>U: Foto-Upload anzeigen
    U->>V: Fotos hochladen
    V->>E: Weiterleitung mit Signatur
    E->>E: Rückkehr-Signatur validieren

Konfiguration

1. Workflow-Modus aktivieren

1. Navigieren Sie zu Ihrem Permanenten Link
2. Klicken Sie auf Bearbeiten
3. Erweitern Sie den Bereich Workflow-Modus
4. Aktivieren Sie den Schalter Workflow-Modus
5. Konfigurieren Sie die Weiterleitungs-URL
6. Kopieren Sie das Workflow-Secret

2. Weiterleitungs-URL konfigurieren

Legen Sie die URL fest, zu der Benutzer nach Abschluss der Uploads zurückkehren:

https://ihr-system.com/fertig?id={submission_id}&ref={reference}&sig={signature}

Verfügbare Platzhalter

Platzhalter	Beschreibung	Beispiel
{submission_id}	Visiono-Einreichungs-ID	pls_123
{unique_value}	Übergebener eindeutiger Feldwert	ABC123
{reference}	Übergebene externe Referenz	ticket-456
{photo_count}	Anzahl hochgeladener Fotos	5
{timestamp}	Unix-Zeitstempel	1705500000
{signature}	HMAC-Signatur zur Verifizierung	abc123...

Signierte URLs generieren

URL-Parameter

Param	Langer Name	Beschreibung	Erforderlich
uv	unique_value	Eindeutige Kennung	Ja
src	source	Quellsystem	Ja
ref	reference	Externe Referenz	Ja
ts	timestamp	Unix-Zeitstempel	Ja
sig	signature	HMAC-SHA256-Signatur	Ja

Signatur-Algorithmus

payload = "{unique_value}|{source}|{reference}|{timestamp}"
signature = HMAC-SHA256(payload, workflow_secret)

PHP-Beispiel

<?php

$workflowSecret = 'ihr-workflow-secret';
$slug = 'schadensbericht';

// Daten
$uniqueValue = 'ABC123';
$source = 'zendesk';
$reference = 'ticket-456';
$timestamp = time();

// Signatur generieren
$payload = "{$uniqueValue}|{$source}|{$reference}|{$timestamp}";
$signature = hash_hmac('sha256', $payload, $workflowSecret);

// URL erstellen
$baseUrl = "https://visiono.io/s/{$slug}";
$params = http_build_query([
    'uv' => $uniqueValue,
    'src' => $source,
    'ref' => $reference,
    'ts' => $timestamp,
    'sig' => $signature,
]);

$url = "{$baseUrl}?{$params}";
// https://visiono.io/s/schadensbericht?uv=ABC123&src=zendesk&ref=ticket-456&ts=1705500000&sig=abc123...

JavaScript-Beispiel

const crypto = require('crypto');

const workflowSecret = 'ihr-workflow-secret';
const slug = 'schadensbericht';

// Daten
const uniqueValue = 'ABC123';
const source = 'zendesk';
const reference = 'ticket-456';
const timestamp = Math.floor(Date.now() / 1000);

// Signatur generieren
const payload = `${uniqueValue}|${source}|${reference}|${timestamp}`;
const signature = crypto
  .createHmac('sha256', workflowSecret)
  .update(payload)
  .digest('hex');

// URL erstellen
const params = new URLSearchParams({
  uv: uniqueValue,
  src: source,
  ref: reference,
  ts: timestamp,
  sig: signature,
});

const url = `https://visiono.io/s/${slug}?${params}`;

Python-Beispiel

import hmac
import hashlib
import time
from urllib.parse import urlencode

workflow_secret = 'ihr-workflow-secret'
slug = 'schadensbericht'

# Daten
unique_value = 'ABC123'
source = 'zendesk'
reference = 'ticket-456'
timestamp = int(time.time())

# Signatur generieren
payload = f"{unique_value}|{source}|{reference}|{timestamp}"
signature = hmac.new(
    workflow_secret.encode(),
    payload.encode(),
    hashlib.sha256
).hexdigest()

# URL erstellen
params = urlencode({
    'uv': unique_value,
    'src': source,
    'ref': reference,
    'ts': timestamp,
    'sig': signature,
})

url = f"https://visiono.io/s/{slug}?{params}"

Weiterleitungs-Signatur validieren

Wenn Benutzer zurückgeleitet werden, verifizieren Sie die Signatur, um Datenintegrität sicherzustellen.

Rückkehr-URL-Beispiel

https://ihr-system.com/fertig?sub=pls_123&ref=ticket-456&cnt=5&ts=1705500100&sig=def456...

Signaturverifizierung

Die Rückkehr-Signatur wird berechnet als:

payload = "{submission_id}|{unique_value}|{reference}|{photo_count}|{timestamp}"
expected_signature = HMAC-SHA256(payload, workflow_secret)

PHP-Verifizierung

<?php

$workflowSecret = 'ihr-workflow-secret';

// Parameter aus Weiterleitung holen
$submissionId = $_GET['sub'];
$uniqueValue = $_GET['uv'];
$reference = $_GET['ref'];
$photoCount = $_GET['cnt'];
$timestamp = $_GET['ts'];
$receivedSignature = $_GET['sig'];

// Signatur verifizieren
$payload = "{$submissionId}|{$uniqueValue}|{$reference}|{$photoCount}|{$timestamp}";
$expectedSignature = hash_hmac('sha256', $payload, $workflowSecret);

if (hash_equals($expectedSignature, $receivedSignature)) {
    // Signatur gültig - Einreichung verarbeiten
    echo "Fotos erfolgreich eingereicht!";
} else {
    // Signatur ungültig - ablehnen
    http_response_code(400);
    echo "Ungültige Signatur";
}

Link-Ablauf

Signierte URLs laufen standardmäßig nach 1 Stunde ab. Dies verhindert:

• Wiederverwendung alter Links
• Replay-Angriffe
• Veraltete Daten

Wenn ein Benutzer einen abgelaufenen Link öffnet, sieht er eine "Link abgelaufen"-Fehlerseite.

Sicherheits-Best-Practices

Ihr Secret schützen

• Workflow-Secret sicher speichern
• Niemals in clientseitigem Code offenlegen
• Secrets regelmäßig rotieren
• Umgebungsvariablen verwenden

Zeitstempel validieren

$maxAge = 3600; // 1 Stunde
if (time() - $timestamp > $maxAge) {
    // Link abgelaufen
    return false;
}

HTTPS verwenden

Verwenden Sie immer HTTPS für:

• Ihre Weiterleitungs-URLs
• Alle API-Aufrufe
• Webhook-Endpunkte

Fehlerseiten

Benutzer können Fehlerseiten sehen für:

Fehler	Ursache	Lösung
Fehlende Parameter	URL fehlen erforderliche Parameter	URL-Generierung prüfen
Ungültige Signatur	Signatur stimmt nicht überein	Secret und Algorithmus verifizieren
Link abgelaufen	Zeitstempel > 1 Stunde alt	Neuen Link generieren

Webhook-Integration

Workflow-Modus funktioniert mit Webhooks. Das submission.created-Ereignis enthält:

{
  "event": "submission.created",
  "data": {
    "photo_request": {
      "id": "pr_123",
      "custom_slug": "schadensbericht"
    },
    "permanent_link_submission": {
      "id": "pls_456",
      "unique_field_value": "ABC123",
      "external_source": "zendesk",
      "external_reference": "ticket-456"
    }
  }
}

Anwendungsfälle

Zendesk-Ticket-Fotos

1. Agent sendet Kunden signierten Link
2. Kunde lädt Schadensfotos hoch
3. Kunde wird zurück zum Ticket geleitet
4. Webhook aktualisiert Ticket mit Fotos

Versicherungsansprüche

1. Anspruchssystem generiert signierten Link
2. Versicherungsnehmer dokumentiert Schaden
3. Weiterleitung zur Anspruchsbestätigung
4. Fotos werden automatisch mit Anspruch verknüpft

Außendienst

1. Techniker erhält Arbeitsauftrag
2. Öffnet signierten Link vom Handy
3. Dokumentiert abgeschlossene Arbeit
4. Weiterleitung zur Auftragsabschlussseite

Fehlerbehebung

Signatur-Mismatch

1. Verifizieren, dass Secret genau übereinstimmt
2. Parameter-Encoding prüfen
3. Zeitstempelformat bestätigen
4. Sicherstellen, dass Payload-Reihenfolge korrekt ist

Weiterleitung funktioniert nicht

1. Verifizieren, dass Weiterleitungs-URL konfiguriert ist
2. Platzhalter-Syntax prüfen
3. Bestätigen, dass URL korrekt kodiert ist

Link sofort abgelaufen

1. Server-Zeitsynchronisation prüfen
2. Verifizieren, dass Zeitstempel Unix-Format ist
3. Sicherstellen, dass Zeitstempel aktuell ist

Verwandte Ressourcen

• Permanente Links - Link-Konfiguration
• Webhooks - Ereignisbenachrichtigungen
• API-Referenz - Vollständige API-Dokumentation