Entwickler
Auf VEPRA aufbauen
Jede Handlung, die eine Person in der App vornimmt, ist ein benannter Befehl mit Schema und Berechtigung. Dieselben Befehle werden mit einem API-Schlüssel, aus Webhooks und vom Agenten aufgerufen. Es gibt keine zweite API.
API-Schlüssel
Ein Schlüssel ist ein „service“-Akteur des Unternehmens mit den Berechtigungen, die Sie beim Anlegen wählen (nur aus Ihren eigenen, nie members.manage). Legen Sie ihn unter Unternehmen → Agent & API-Schlüssel an; das Token wird einmal angezeigt, und nur sein Hash wird gespeichert.
Ein Schlüssel erreicht nur sein eigenes Unternehmen (jede andere Route antwortet mit 403), läuft ab, wann Sie es sagen, und wird mit einem Klick widerrufen. Er hat kein MFA: Befehle, die einen frischen Code verlangen, werden immer abgelehnt.
Einen Befehl aufrufen
curl -X POST https://vepra.ai/v1/businesses/<BIZNESI>/commands/contact.save \
-H "Authorization: Bearer vak_..." \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"displayName":"Arta Leka","kind":"person","email":"[email protected]","phone":"+355691234567"}'Die Quittung
{
"operationId": "3f1c...", "command": "contact.save", "status": "applied",
"resources": [{ "type": "Contact", "id": "a51d...", "version": 1 }],
"eventIds": ["..."], "correlationId": "...", "warnings": []
}Status: applied, awaiting_approval (Freigabe innerhalb der Plattform), pending_external (wartet auf eine externe Partei). Fehler: 401 unbekannter oder abgelaufener Schlüssel, 403 außerhalb der Berechtigungen oder des Unternehmens, 409 veraltete Version (expectedVersion), 422 ungültige Eingabe mit fieldErrors.
Idempotency-Key: Derselbe Wert zweimal liefert dieselbe Quittung, ohne die Aktion zu wiederholen.
Befehle
Die vollständige Liste mit den Eingabeschemata steht im OpenAPI-Dokument: /v1/openapi.json (Befehlsroute: POST /v1/businesses/{businessId}/commands/{name}). Die Schemata heißen Input_<command with underscores>, z. B. Input_contact_save.
Am häufigsten genutzt: contact.save, lead.save, booking.hold / booking.confirm, quote.draft / quote.send, task.create, work.create, consent.record.
Lesezugriffe nutzen dieselben GET-Routen wie die App, z. B. GET /v1/businesses/{businessId}/contacts?limit=50, mit der passenden .read-Berechtigung.
Eingehende Webhooks
Eine öffentliche Adresse, an die Ihre Systeme (Formulare, Zahlungen, Activepieces, n8n, Zapier) per POST senden. Legen Sie sie auf derselben Seite an: ein Name, was sie tut (nur Workflows starten oder einen Befehl aus einer Vorlage ausführen) und das Geheimnis, einmal angezeigt.
Der Absender belegt das Geheimnis mit X-Vepra-Signature: sha256=<HMAC-SHA256 of the body> oder, wenn er nicht signieren kann, mit X-Vepra-Token: <secret>. Ohne Nachweis: 401. Unbekannte oder deaktivierte Adresse: 404. Abgelehnte Aufrufe werden nie aufgezeichnet.
Ein Aufruf mit dem Token
curl -X POST https://vepra.ai/v1/hooks/<HOOK_ID> \
-H "X-Vepra-Token: vhk_..." \
-H "Content-Type: application/json" \
-d '{"name":"Arta Leka","email":"[email protected]","phone":"+355691234567"}'Signieren (Node.js)
import { createHmac } from 'node:crypto';
const signature = 'sha256=' + createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
// -> header X-Vepra-Signature: sha256=...Die Befehlsvorlage
{ "displayName": "{{name}}", "kind": "person", "email": "{{email}}", "phone": "{{phone}}", "notes": "Nga {{source}}" }{{field.subfield}} nimmt seinen Wert aus dem Körper der Zustellung; ein ganzer Wert behält seinen Typ (Zahl, Liste), ein fehlender Wert lässt das Feld weg. Jede Zustellung löst WebhookReceived aus, einen Workflow-Trigger, mit contactId, wenn der Befehl einen Kontakt erzeugt hat.
Ausgehende Webhooks
Vepra sendet die Ereignisse Ihres Unternehmens an eine öffentliche https-Adresse, die Sie angeben: Kontakt gespeichert, Interessent, Buchung bestätigt, Angebot angenommen, Arbeit angelegt … (alle oder nur die, die Sie wählen). Private Adressen (10.x, 192.168.x, localhost) werden abgelehnt.
Jede Zustellung ist ein JSON-POST mit drei Headern: X-Vepra-Event, X-Vepra-Delivery und X-Vepra-Signature (sha256=HMAC-SHA256 des Körpers mit dem Geheimnis, das Sie einmal erhalten haben). Antworten Sie innerhalb von 10 Sekunden mit 2xx; Weiterleitungen werden nicht verfolgt.
Wiederholungen nach 1 Min., 5 Min., 30 Min., 2 Std. und 12 Std.; nach 5 Versuchen wird die Zustellung aufgegeben, nach 20 aufeinanderfolgenden Fehlern wird die Adresse deaktiviert (auf der Seite wieder aktivieren). „Test“ sendet ein HookTest.
Der Körper der Zustellung
{
"id": "d3b7...", // X-Vepra-Delivery
"event": "ContactSaved", // X-Vepra-Event
"occurredAt": "2026-09-17T18:40:00.000Z",
"business": "58a7...",
"aggregate": { "type": "Contact", "id": "a51d...", "version": 3 },
"payload": { "...": "..." },
"attempt": 1
}Prüfung (Node.js)
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyVepra(rawBody, signatureHeader, secret) {
const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
const a = Buffer.from(signatureHeader ?? ''), b = Buffer.from(expected);
return a.length === b.length && timingSafeEqual(a, b);
}Prüfung (PHP)
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$ok = hash_equals($expected, $_SERVER['HTTP_X_VEPRA_SIGNATURE'] ?? '');
Der Agent
Der Agent nimmt ein Ziel in einfachen Worten entgegen und baut die Aufrufe selbst: Seine Werkzeuge sind genau die Vertragsbefehle im Rahmen der Berechtigungen des Akteurs. Rechnungen, Zahlungen, Gehälter, Lizenzen, Zeiträume und Mitgliedschaften führt der Agent nie aus; sie bleiben Vorschläge, die eine Person ausführt.
Geplante Läufe führen ein Ziel im Takt aus (stündlich, täglich, werktags, wöchentlich), als eigener Akteur, hinterlassen eine Aufgabe unter Aufgaben und benachrichtigen den Ersteller. Erforderlich ist ein Modell mit Tool-Use, das unter API-Verbindungen angeschlossen ist.
Workflows
Der Schritt „Befehl aufrufen“ eines Workflows läuft ebenfalls durch die Pipeline, als Akteur „Workflow“ des Unternehmens, mit typisierten Parametern (das Kontakt-Tag, die Buchungsaktion, der Gesprächskanal …). Ereignisse, die dieser Akteur auslöst, starten keine anderen Workflows, es gibt also keine endlosen Ketten. Der Trigger WebhookReceived verbindet externe Systeme mit Workflows.
Sicherheit
Tokens nie in URLs; Schlüssel werden als Hash gespeichert, Geheimnisse versiegelt. Jeder Aufruf wird mit dem Service-Akteur geprüft, der ihn ausgeführt hat. Grenzen: bis zu 10 Schlüssel, 10 Pläne, 20 eingehende Webhooks und 10 ausgehende Adressen je Unternehmen; eingehender Körper bis 1 MB. Das Ratenlimit der API gilt auch für Schlüssel.
Fragen oder ein höheres Limit: [email protected].